00001 /** @file 00002 00003 Public VConnection declaration and associated declarations 00004 00005 @section license License 00006 00007 Licensed to the Apache Software Foundation (ASF) under one 00008 or more contributor license agreements. See the NOTICE file 00009 distributed with this work for additional information 00010 regarding copyright ownership. The ASF licenses this file 00011 to you under the Apache License, Version 2.0 (the 00012 "License"); you may not use this file except in compliance 00013 with the License. You may obtain a copy of the License at 00014 00015 http://www.apache.org/licenses/LICENSE-2.0 00016 00017 Unless required by applicable law or agreed to in writing, software 00018 distributed under the License is distributed on an "AS IS" BASIS, 00019 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00020 See the License for the specific language governing permissions and 00021 limitations under the License. 00022 00023 */ 00024 00025 #if !defined (_I_VConnection_h_) 00026 #define _I_VConnection_h_ 00027 00028 #include "libts.h" 00029 #include "I_EventSystem.h" 00030 #if !defined(I_VIO_h) 00031 #error "include I_VIO.h" 00032 -- -include I_VIO.h 00033 #endif 00034 00035 // 00036 // Data Types 00037 // 00038 #define VCONNECTION_CACHE_DATA_BASE 0 00039 #define VCONNECTION_NET_DATA_BASE 100 00040 #define VCONNECTION_API_DATA_BASE 200 00041 00042 // 00043 // Event signals 00044 // 00045 00046 #define VC_EVENT_NONE EVENT_NONE 00047 00048 /** When a Continuation is first scheduled on a processor. */ 00049 #define VC_EVENT_IMMEDIATE EVENT_IMMEDIATE 00050 00051 #define VC_EVENT_READ_READY VC_EVENT_EVENTS_START 00052 00053 /** 00054 Any data in the accociated buffer *will be written* when the 00055 Continuation returns. 00056 00057 */ 00058 #define VC_EVENT_WRITE_READY (VC_EVENT_EVENTS_START+1) 00059 00060 #define VC_EVENT_READ_COMPLETE (VC_EVENT_EVENTS_START+2) 00061 #define VC_EVENT_WRITE_COMPLETE (VC_EVENT_EVENTS_START+3) 00062 00063 /** 00064 No more data (end of stream). It should be interpreted by a 00065 protocol engine as either a COMPLETE or ERROR. 00066 00067 */ 00068 #define VC_EVENT_EOS (VC_EVENT_EVENTS_START+4) 00069 00070 #define VC_EVENT_ERROR EVENT_ERROR 00071 00072 /** 00073 VC_EVENT_INACTIVITY_TIMEOUT indiates that the operation (read or write) has: 00074 -# been enabled for more than the inactivity timeout period 00075 (for a read, there has been space in the buffer) 00076 (for a write, there has been data in the buffer) 00077 -# no progress has been made 00078 (for a read, no data has been read from the connection) 00079 (for a write, no data has been written to the connection) 00080 00081 */ 00082 #define VC_EVENT_INACTIVITY_TIMEOUT (VC_EVENT_EVENTS_START+5) 00083 00084 /** 00085 Total time for some operation has been exeeded, regardless of any 00086 intermediate progress. 00087 00088 */ 00089 #define VC_EVENT_ACTIVE_TIMEOUT (VC_EVENT_EVENTS_START+6) 00090 00091 #define VC_EVENT_OOB_COMPLETE (VC_EVENT_EVENTS_START+7) 00092 00093 // 00094 // Event names 00095 // 00096 00097 // 00098 // VC_EVENT_READ_READ occurs when data *has been written* into 00099 // the associated buffer. 00100 // 00101 // VC_EVENT_ERROR indicates that some error has occured. The 00102 // "data" will be either 0 if the errno is unavailable or errno. 00103 // 00104 // VC_EVENT_INTERVAL indidates that an interval timer has expired. 00105 // 00106 00107 // 00108 // Event return codes 00109 // 00110 #define VC_EVENT_DONE CONTINUATION_DONE 00111 #define VC_EVENT_CONT CONTINUATION_CONT 00112 00113 ////////////////////////////////////////////////////////////////////////////// 00114 // 00115 // Support Data Structures 00116 // 00117 ////////////////////////////////////////////////////////////////////////////// 00118 00119 /** Used in VConnection::shutdown(). */ 00120 enum ShutdownHowTo_t 00121 { 00122 IO_SHUTDOWN_READ = 0, 00123 IO_SHUTDOWN_WRITE, 00124 IO_SHUTDOWN_READWRITE 00125 }; 00126 00127 /** Used in VConnection::get_data(). */ 00128 enum TSApiDataType 00129 { 00130 TS_API_DATA_READ_VIO = VCONNECTION_API_DATA_BASE, 00131 TS_API_DATA_WRITE_VIO, 00132 TS_API_DATA_OUTPUT_VC, 00133 TS_API_DATA_CLOSED 00134 }; 00135 00136 extern "C" { 00137 typedef struct tsapi_vio* TSVIO; 00138 } 00139 00140 /** 00141 Base class for the connection classes that provide IO capabilities. 00142 00143 The VConnection class is an abstract representation of a uni or 00144 bi-directional data conduit returned by a Processor. In a sense, 00145 they serve a similar purpose to file descriptors. A VConnection 00146 is a pure base class that defines methods to perform stream IO. 00147 It is also a Continuation that is called back from processors. 00148 00149 */ 00150 class VConnection:public Continuation 00151 { 00152 public: 00153 00154 virtual ~ VConnection(); 00155 00156 /** 00157 Read data from the VConnection. 00158 00159 Called by a state machine to read data from the VConnection. 00160 Processors implementing read functionality take out lock, put 00161 new bytes on the buffer and call the continuation back before 00162 releasing the lock in order to enable the state machine to 00163 handle transfer schemes where the end of a given transaction 00164 is marked by a special character (ie: NNTP). 00165 00166 <b>Possible Event Codes</b> 00167 00168 On the callback to the continuation, the VConnection may use 00169 on of the following values for the event code: 00170 00171 <table border="1"> 00172 <tr> 00173 <td align="center"><b>Event code</b></td> 00174 <td align="center"><b>Meaning</b></td> 00175 </tr> 00176 <tr> 00177 <td>VC_EVENT_READ_READY</td> 00178 <td>Data has been added to the buffer or the buffer is full</td> 00179 </tr> 00180 <tr> 00181 <td>VC_EVENT_READ_COMPLETE</td> 00182 <td>The amount of data indicated by 'nbytes' has been read into the 00183 buffer</td> 00184 </tr> 00185 <tr> 00186 <td>VC_EVENT_EOS</td> 00187 <td>The stream being read from has been shutdown</td> 00188 </tr> 00189 <tr> 00190 <td>VC_EVENT_ERROR</td> 00191 <td>An error occurred during the read</td> 00192 </tr> 00193 </table> 00194 00195 @param c Continuation to be called back with events. 00196 @param nbytes Number of bytes to read. If unknown, nbytes must 00197 be set to INT64_MAX. 00198 @param buf buffer to read into. 00199 @return VIO representing the scheduled IO operation. 00200 00201 */ 00202 virtual VIO *do_io_read(Continuation *c = NULL, int64_t nbytes = INT64_MAX, MIOBuffer *buf = 0) = 0; 00203 00204 /** 00205 Write data to the VConnection. 00206 00207 This method is called by a state machine to write data to the 00208 VConnection. 00209 00210 <b>Possible Event Codes</b> 00211 00212 On the callback to the continuation, the VConnection may use 00213 on of the following event codes: 00214 00215 <table border="1"> 00216 <tr> 00217 <td align="center"><b>Event code</b></td> 00218 <td align="center"><b>Meaning</b></td> 00219 </tr> 00220 <tr> 00221 <td>VC_EVENT_WRITE_READY</td> 00222 <td>Data was written from the reader or there are no bytes available 00223 for the reader to write.</td> 00224 </tr> 00225 <tr> 00226 <td>VC_EVENT_WRITE_COMPLETE</td> 00227 <td>The amount of data indicated by 'nbytes' has been written to the 00228 VConnection</td> 00229 </tr> 00230 <tr> 00231 <td>VC_EVENT_INACTIVITY_TIMEOUT</td> 00232 <td>No activity was performed for a certain period.</td> 00233 </tr> 00234 <tr> 00235 <td>VC_EVENT_ACTIVE_TIMEOUT</td> 00236 <td>Write operation continued beyond a time limit.</td> 00237 </tr> 00238 <tr> 00239 <td>VC_EVENT_ERROR</td> 00240 <td>An error occurred during the write</td> 00241 </tr> 00242 </table> 00243 00244 @param c Continuation to be called back with events. 00245 @param nbytes Number of bytes to write. If unknown, nbytes must 00246 be set to INT64_MAX. 00247 @param buf Reader whose data is to be read from. 00248 @param owner 00249 @return VIO representing the scheduled IO operation. 00250 00251 */ 00252 virtual VIO *do_io_write(Continuation *c = NULL, 00253 int64_t nbytes = INT64_MAX, IOBufferReader *buf = 0, bool owner = false) = 0; 00254 00255 /** 00256 Indicate that the VConnection is no longer needed. 00257 00258 Once the state machine has finished using this VConnection, it 00259 must call this function to indicate that the VConnection can 00260 be deallocated. After a close has been called, the VConnection 00261 and underlying processor must not send any more events related 00262 to this VConnection to the state machine. Likeswise, the state 00263 machine must not access the VConnection or any VIOs obtained 00264 from it after calling this method. 00265 00266 @param lerrno indicates where a close is a normal close or an 00267 abort. The difference between a normal close and an abort 00268 depends on the underlying type of the VConnection. 00269 00270 */ 00271 virtual void do_io_close(int lerrno = -1) = 0; 00272 00273 /** 00274 Terminate one or both directions of the VConnection. 00275 00276 Indicates that one or both sides of the VConnection should be 00277 terminated. After this call is issued, no further I/O can be 00278 done on the specified direction of the connection. The processor 00279 must not send any further events (including timeout events) to 00280 the state machine, and the state machine must not use any VIOs 00281 from a shutdown direction of the connection. Even if both sides 00282 of a connection are shutdown, the state machine must still call 00283 do_io_close() when it wishes the VConnection to be deallocated. 00284 00285 <b>Possible howto values</b> 00286 00287 <table border="1"> 00288 <tr> 00289 <td align="center"><b>Value</b></td> 00290 <td align="center"><b>Meaning</b></td> 00291 </tr> 00292 <tr> 00293 <td>IO_SHUTDOWN_READ</td> 00294 <td>Indicates that this VConnection should not generate any more 00295 read events</td> 00296 </tr> 00297 <tr> 00298 <td>IO_SHUTDOWN_WRITE</td> 00299 <td>Indicates that this VConnection should not generate any more 00300 write events</td> 00301 </tr> 00302 <tr> 00303 <td>IO_SHUTDOWN_READWRITE</td> 00304 <td>Indicates that this VConnection should not generate any more 00305 read nor write events</td> 00306 </tr> 00307 </table> 00308 00309 @param howto Specifies which direction of the VConnection to 00310 shutdown. 00311 00312 */ 00313 virtual void do_io_shutdown(ShutdownHowTo_t howto) = 0; 00314 00315 VConnection(ProxyMutex *aMutex); 00316 00317 /** @deprecated */ 00318 VIO *do_io(int op, Continuation *c = NULL, int64_t nbytes = INT64_MAX, MIOBuffer *buf = 0, int data = 0); 00319 00320 // Private 00321 // Set continuation on a given vio. The public interface 00322 // is through VIO::set_continuation() 00323 virtual void set_continuation(VIO *vio, Continuation *cont); 00324 00325 // Reenable a given vio. The public interface is through VIO::reenable 00326 virtual void reenable(VIO *vio); 00327 virtual void reenable_re(VIO *vio); 00328 00329 /** 00330 Convenience function to retrieve information from VConnection. 00331 00332 This function is provided as a convenience for state machines 00333 to transmit information from/to a VConnection without breaking 00334 the VConnection abstraction. Its behavior varies depending on 00335 the type of VConnection being used. 00336 00337 @param id Identifier associated to interpret the data field 00338 @param data Value or pointer with state machine or VConnection data. 00339 @return True if the oparation is successful. 00340 00341 */ 00342 virtual bool get_data(int id, void *data) 00343 { 00344 (void) id; 00345 (void) data; 00346 return false; 00347 } 00348 00349 /** 00350 Convenience function to set information into the VConnection. 00351 00352 This function is provided as a convenience for state machines 00353 to transmit information from/to a VConnection without breaking 00354 the VConnection abstraction. Its behavior varies depending on 00355 the type of VConnection being used. 00356 00357 @param id Identifier associated to interpret the data field. 00358 @param data Value or pointer with state machine or VConnection data. 00359 @return True if the oparation is successful. 00360 00361 */ 00362 virtual bool set_data(int id, void *data) 00363 { 00364 (void) id; 00365 (void) data; 00366 return false; 00367 } 00368 00369 public: 00370 00371 /** 00372 The error code from the last error. 00373 00374 Indicates the last error on the VConnection. They are either 00375 system error codes or from the InkErrno.h file. 00376 00377 */ 00378 int lerrno; 00379 }; 00380 00381 struct DummyVConnection: public VConnection 00382 { 00383 virtual VIO *do_io_write(Continuation * /* c ATS_UNUSED */, int64_t /* nbytes ATS_UNUSED */, IOBufferReader * /* buf ATS_UNUSED */, bool /* owner ATS_UNUSED */) { 00384 ink_assert(!"VConnection::do_io_write -- " "cannot use default implementation"); 00385 return NULL; 00386 } 00387 virtual VIO *do_io_read(Continuation * /* c ATS_UNUSED */, int64_t /* nbytes ATS_UNUSED */, MIOBuffer * /* buf ATS_UNUSED */) { 00388 ink_assert(!"VConnection::do_io_read -- " "cannot use default implementation"); 00389 return NULL; 00390 } 00391 virtual void do_io_close(int /* alerrno ATS_UNUSED */) { 00392 ink_assert(!"VConnection::do_io_close -- " "cannot use default implementation"); 00393 } 00394 virtual void do_io_shutdown(ShutdownHowTo_t /* howto ATS_UNUSED */ ) 00395 { 00396 ink_assert(!"VConnection::do_io_shutdown -- " "cannot use default implementation"); 00397 } 00398 DummyVConnection(ProxyMutex *m):VConnection(m) { 00399 } 00400 }; 00401 00402 #endif /*_I_VConnection_h_*/
1.7.1