1 /** @file
2 
3   Public VConnection declaration and associated declarations
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_VConnection_h_)
26 #define _I_VConnection_h_
27 
28 #include "libts.h"
29 #include "I_EventSystem.h"
30 #if !defined(I_VIO_h)
31 #error "include I_VIO.h"
32 -- -include I_VIO.h
33 #endif
34 
35 //
36 // Data Types
37 //
38 #define VCONNECTION_CACHE_DATA_BASE     0
39 #define VCONNECTION_NET_DATA_BASE       100
40 #define VCONNECTION_API_DATA_BASE       200
41 
42 //
43 // Event signals
44 //
45 
46 #define VC_EVENT_NONE                    EVENT_NONE
47 
48 /** When a Continuation is first scheduled on a processor. */
49 #define VC_EVENT_IMMEDIATE               EVENT_IMMEDIATE
50 
51 #define	VC_EVENT_READ_READY              VC_EVENT_EVENTS_START
52 
53 /**
54   Any data in the accociated buffer *will be written* when the
55   Continuation returns.
56 
57 */
58 #define	VC_EVENT_WRITE_READY             (VC_EVENT_EVENTS_START+1)
59 
60 #define	VC_EVENT_READ_COMPLETE           (VC_EVENT_EVENTS_START+2)
61 #define	VC_EVENT_WRITE_COMPLETE          (VC_EVENT_EVENTS_START+3)
62 
63 /**
64   No more data (end of stream). It should be interpreted by a
65   protocol engine as either a COMPLETE or ERROR.
66 
67 */
68 #define	VC_EVENT_EOS                     (VC_EVENT_EVENTS_START+4)
69 
70 #define	VC_EVENT_ERROR                   EVENT_ERROR
71 
72 /**
73   VC_EVENT_INACTIVITY_TIMEOUT indiates that the operation (read or write) has:
74     -# been enabled for more than the inactivity timeout period
75        (for a read, there has been space in the buffer)
76        (for a write, there has been data in the buffer)
77     -# no progress has been made
78        (for a read, no data has been read from the connection)
79        (for a write, no data has been written to the connection)
80 
81 */
82 #define	VC_EVENT_INACTIVITY_TIMEOUT      (VC_EVENT_EVENTS_START+5)
83 
84 /**
85   Total time for some operation has been exeeded, regardless of any
86   intermediate progress.
87 
88 */
89 #define	VC_EVENT_ACTIVE_TIMEOUT          (VC_EVENT_EVENTS_START+6)
90 
91 #define	VC_EVENT_OOB_COMPLETE            (VC_EVENT_EVENTS_START+7)
92 
93 //
94 // Event names
95 //
96 
97 //
98 // VC_EVENT_READ_READ occurs when data *has been written* into
99 // the associated buffer.
100 //
101 // VC_EVENT_ERROR indicates that some error has occured.  The
102 // "data" will be either 0 if the errno is unavailable or errno.
103 //
104 // VC_EVENT_INTERVAL indidates that an interval timer has expired.
105 //
106 
107 //
108 // Event return codes
109 //
110 #define VC_EVENT_DONE                CONTINUATION_DONE
111 #define VC_EVENT_CONT                CONTINUATION_CONT
112 
113 //////////////////////////////////////////////////////////////////////////////
114 //
115 //      Support Data Structures
116 //
117 //////////////////////////////////////////////////////////////////////////////
118   class VConnection;
119 
120 typedef int (VConnection::*VConnectionHandler) (int event, void *data);
121 
122 /** Used in VConnection::shutdown(). */
123 enum ShutdownHowTo_t
124 {
125   IO_SHUTDOWN_READ = 0,
126   IO_SHUTDOWN_WRITE,
127   IO_SHUTDOWN_READWRITE
128 };
129 
130 /**
131   Base class for the connection classes that provide IO capabilities.
132 
133   The VConnection class is an abstract representation of a uni or
134   bi-directional data conduit returned by a Processor. In a sense,
135   they serve a similar purpose to file descriptors. A VConnection
136   is a pure base class that defines methods to perform stream IO.
137   It is also a Continuation that is called back from processors.
138 
139 */
140 class VConnection:public Continuation
141 {
142 public:
143 
144   virtual ~ VConnection();
145 
146   /**
147     Read data from the VConnection.
148 
149     Called by a state machine to read data from the VConnection.
150     Processors implementing read functionality take out lock, put
151     new bytes on the buffer and call the continuation back before
152     releasing the lock in order to enable the state machine to
153     handle transfer schemes where the end of a given transaction
154     is marked by a special character (ie: NNTP).
155 
156     <b>Possible Event Codes</b>
157 
158     On the callback to the continuation, the VConnection may use
159     on of the following values for the event code:
160 
161     <table border="1">
162       <tr>
163         <td align="center"><b>Event code</b></td>
164         <td align="center"><b>Meaning</b></td>
165       </tr>
166       <tr>
167         <td>VC_EVENT_READ_READY</td>
168         <td>Data has been added to the buffer or the buffer is full</td>
169       </tr>
170       <tr>
171         <td>VC_EVENT_READ_COMPLETE</td>
172         <td>The amount of data indicated by 'nbytes' has been read into the
173             buffer</td>
174       </tr>
175       <tr>
176         <td>VC_EVENT_EOS</td>
177         <td>The stream being read from has been shutdown</td>
178       </tr>
179       <tr>
180         <td>VC_EVENT_ERROR</td>
181         <td>An error occurred during the read</td>
182       </tr>
183     </table>
184 
185     @param c Continuation to be called back with events.
186     @param nbytes Number of bytes to read. If unknown, nbytes must
187       be set to INT64_MAX.
188     @param buf buffer to read into.
189     @return VIO representing the scheduled IO operation.
190 
191   */
192   virtual VIO *do_io_read(Continuation *c = NULL, int64_t nbytes = INT64_MAX, MIOBuffer *buf = 0) = 0;
193 
194   /**
195     Write data to the VConnection.
196 
197     This method is called by a state machine to write data to the
198     VConnection.
199 
200     <b>Possible Event Codes</b>
201 
202     On the callback to the continuation, the VConnection may use
203     on of the following event codes:
204 
205     <table border="1">
206       <tr>
207         <td align="center"><b>Event code</b></td>
208         <td align="center"><b>Meaning</b></td>
209       </tr>
210       <tr>
211         <td>VC_EVENT_WRITE_READY</td>
212         <td>Data was written from the reader or there are no bytes available
213         for the reader to write.</td>
214       </tr>
215       <tr>
216         <td>VC_EVENT_WRITE_COMPLETE</td>
217         <td>The amount of data indicated by 'nbytes' has been written to the
218             VConnection</td>
219       </tr>
220       <tr>
221         <td>VC_EVENT_INACTIVITY_TIMEOUT</td>
222         <td>No activity was performed for a certain period.</td>
223       </tr>
224       <tr>
225         <td>VC_EVENT_ACTIVE_TIMEOUT</td>
226         <td>Write operation continued beyond a time limit.</td>
227       </tr>
228       <tr>
229         <td>VC_EVENT_ERROR</td>
230         <td>An error occurred during the write</td>
231       </tr>
232     </table>
233 
234     @param c Continuation to be called back with events.
235     @param nbytes Number of bytes to write. If unknown, nbytes must
236       be set to INT64_MAX.
237     @param buf Reader whose data is to be read from.
238     @param owner
239     @return VIO representing the scheduled IO operation.
240 
241   */
242   virtual VIO *do_io_write(Continuation *c = NULL,
243                            int64_t nbytes = INT64_MAX, IOBufferReader *buf = 0, bool owner = false) = 0;
244 
245   /**
246     Indicate that the VConnection is no longer needed.
247 
248     Once the state machine has finished using this VConnection, it
249     must call this function to indicate that the VConnection can
250     be deallocated.  After a close has been called, the VConnection
251     and underlying processor must not send any more events related
252     to this VConnection to the state machine. Likeswise, the state
253     machine must not access the VConnection or any VIOs obtained
254     from it after calling this method.
255 
256     @param lerrno indicates where a close is a normal close or an
257       abort. The difference between a normal close and an abort
258       depends on the underlying type of the VConnection.
259 
260   */
261   virtual void do_io_close(int lerrno = -1) = 0;
262 
263   /**
264     Terminate one or both directions of the VConnection.
265 
266     Indicates that one or both sides of the VConnection should be
267     terminated. After this call is issued, no further I/O can be
268     done on the specified direction of the connection. The processor
269     must not send any further events (including timeout events) to
270     the state machine, and the state machine must not use any VIOs
271     from a shutdown direction of the connection. Even if both sides
272     of a connection are shutdown, the state machine must still call
273     do_io_close() when it wishes the VConnection to be deallocated.
274 
275     <b>Possible howto values</b>
276 
277     <table border="1">
278       <tr>
279         <td align="center"><b>Value</b></td>
280         <td align="center"><b>Meaning</b></td>
281       </tr>
282       <tr>
283         <td>IO_SHUTDOWN_READ</td>
284         <td>Indicates that this VConnection should not generate any more
285         read events</td>
286       </tr>
287       <tr>
288         <td>IO_SHUTDOWN_WRITE</td>
289         <td>Indicates that this VConnection should not generate any more
290         write events</td>
291       </tr>
292       <tr>
293         <td>IO_SHUTDOWN_READWRITE</td>
294         <td>Indicates that this VConnection should not generate any more
295         read nor write events</td>
296       </tr>
297     </table>
298 
299     @param howto Specifies which direction of the VConnection to
300       shutdown.
301 
302   */
303   virtual void do_io_shutdown(ShutdownHowTo_t howto) = 0;
304 
305     VConnection(ProxyMutex *aMutex);
306 
307 #if defined (_IOCORE_WIN32_WINNT)
308   virtual void set_nbytes(VIO *vio, int64_t nbytes);
309 #endif
310 
311   /** @deprecated */
312   VIO *do_io(int op, Continuation *c = NULL, int64_t nbytes = INT64_MAX, MIOBuffer *buf = 0, int data = 0);
313 
314   // Private
315   // Set continuation on a given vio. The public interface
316   // is through VIO::set_continuation()
317   virtual void set_continuation(VIO *vio, Continuation *cont);
318 
319   // Reenable a given vio.  The public interface is through VIO::reenable
320   virtual void reenable(VIO *vio);
321   virtual void reenable_re(VIO *vio);
322 
323   /**
324     Convenience function to retreive information from VConnection.
325 
326     This function is provided as a convenience for state machines
327     to transmit information from/to a VConnection without breaking
328     the VConnection abstraction. Its behavior varies depending on
329     the type of VConnection being used.
330 
331     @param id Identifier associated to interpret the data field
332     @param data Value or pointer with state machine or VConnection data.
333     @return True if the oparation is successful.
334 
335   */
336   virtual bool get_data(int id, void *data)
337   {
338     (void) id;
339     (void) data;
340     return false;
341   }
342 
343   /**
344     Convenience function to set information into the VConnection.
345 
346     This function is provided as a convenience for state machines
347     to transmit information from/to a VConnection without breaking
348     the VConnection abstraction. Its behavior varies depending on
349     the type of VConnection being used.
350 
351     @param id Identifier associated to interpret the data field.
352     @param data Value or pointer with state machine or VConnection data.
353     @return True if the oparation is successful.
354 
355   */
356   virtual bool set_data(int id, void *data)
357   {
358     (void) id;
359     (void) data;
360     return false;
361   }
362 
363 public:
364 
365   /**
366     The error code from the last error.
367 
368     Indicates the last error on the VConnection. They are either
369     system error codes or from the InkErrno.h file.
370 
371   */
372   int lerrno;
373 };
374 
375 struct DummyVConnection: public VConnection
376 {
377   virtual VIO *do_io_write(Continuation *c = NULL, int64_t nbytes = INT64_MAX, IOBufferReader *buf = 0, bool owner = false) {
378     (void) c;
379     (void) nbytes;
380     (void) buf;
381     (void) owner;
382     ink_debug_assert(!"VConnection::do_io_write -- " "cannot use default implementation");
383     return NULL;
384   }
385   virtual VIO *do_io_read(Continuation *c = NULL, int64_t nbytes = INT64_MAX, MIOBuffer *buf = 0) {
386     (void) c;
387     (void) nbytes;
388     (void) buf;
389     ink_debug_assert(!"VConnection::do_io_read -- " "cannot use default implementation");
390     return NULL;
391   }
392   virtual void do_io_close(int alerrno = -1) {
393     (void) alerrno;
394     ink_debug_assert(!"VConnection::do_io_close -- " "cannot use default implementation");
395   }
396   virtual void do_io_shutdown(ShutdownHowTo_t howto)
397   {
398     (void) howto;
399     ink_debug_assert(!"VConnection::do_io_shutdown -- " "cannot use default implementation");
400   }
401 #ifdef _IOCORE_WIN32_WINNT
402   virtual void set_nbytes(VIO *vio, int64_t nbytes)
403   {
404     (void) vio;
405     (void) nbytes;
406     ink_debug_assert(!"DummyVConnection::set_nbytes -- " "cannot use default implementation");
407   }
408 #endif
409 DummyVConnection(ProxyMutex *m):VConnection(m) {
410   }
411 };
412 
413 #endif /*_I_VConnection_h_*/
414