Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Namespace Members | Class Members | File Members | Related Pages

wvstream.h

Go to the documentation of this file.
00001 /* -*- Mode: C++ -*-
00002  * Worldvisions Weaver Software:
00003  *   Copyright (C) 1997-2002 Net Integration Technologies, Inc.
00004  * 
00005  * Provides basic streaming I/O support.
00006  */ 
00007 #ifndef __WVSTREAM_H
00008 #define __WVSTREAM_H
00009 
00010 #include "wvxplc.h"
00011 #include "wverror.h"
00012 #include "wvbuf.h"
00013 #include "wvcallback.h"
00014 #include "wvtimeutils.h"
00015 #include <errno.h>
00016 #include <limits.h>
00017 
00018 #ifdef _WIN32
00019 #include <time.h>
00020 #include <Winsock2.h>
00021 #include <ws2tcpip.h>
00022 #else
00023 #include <unistd.h> // not strictly necessary, but EVERYBODY uses this...
00024 #include <sys/time.h>
00025 #endif
00026 
00027 class WvAddr;
00028 class WvTask;
00029 class WvTaskMan;
00030 class WvStream;
00031 
00032 // parameters are: owning-stream, userdata
00033 typedef WvCallback<void, WvStream&, void*> WvStreamCallback;
00034 
00035 class IWvStream : public IObject, public WvError
00036 {
00037 public:
00038     /**
00039      * A SelectRequest is a convenient way to remember what we want to do
00040      * to a particular stream: read from it, write to it, or check for
00041      * exceptions.
00042      */
00043     struct SelectRequest {
00044         bool readable, writable, isexception;
00045         
00046         SelectRequest() { }
00047         SelectRequest(bool r, bool w, bool x = false)
00048                 { readable = r; writable = w; isexception = x; }
00049         
00050         SelectRequest &operator |= (const SelectRequest &r)
00051                 { readable |= r.readable; writable |= r.writable;
00052                     isexception |= r.isexception; return *this; }
00053     };
00054     
00055     /**
00056      * the data structure used by pre_select()/post_select() and internally
00057      * by select().
00058      */
00059     struct SelectInfo {
00060         fd_set read, write, except; // set by pre_select, read by post_select
00061         SelectRequest wants;        // what is the user looking for?
00062         int max_fd;                 // largest fd in read, write, or except
00063         time_t msec_timeout;        // max time to wait, or -1 for forever
00064         bool inherit_request;       // 'wants' values passed to child streams
00065         bool global_sure;           // should we run the globalstream callback
00066     };
00067     
00068     IWvStream();
00069     virtual ~IWvStream();
00070     virtual void close() = 0;
00071     virtual bool isok() const = 0;
00072     virtual void callback() = 0;
00073     
00074     // FIXME: these really have no place in the interface...
00075     virtual int getrfd() const = 0;
00076     virtual int getwfd() const = 0;
00077 
00078     // FIXME: evil, should go away (or be changed to localaddr/remoteaddr)
00079     virtual const WvAddr *src() const = 0;
00080     
00081     // needed for select().
00082     // Some say that pre_select() should go away.
00083     virtual bool pre_select(SelectInfo &si) = 0;
00084     virtual bool post_select(SelectInfo &si) = 0;
00085     
00086     // these are now the official way to get/put data to your stream.
00087     // The old uread() and uwrite() are just implementation details!
00088     virtual size_t read(void *buf, size_t count) = 0;
00089     virtual size_t write(const void *buf, size_t count) = 0;
00090 
00091     // FIXME: these are the new fancy versions, but WvBuf needs to have
00092     // a safely abstracted interface class (IWvBuf) before IWvStream will
00093     // really be safe, if we include these.
00094     virtual size_t read(WvBuf &outbuf, size_t count) = 0;
00095     virtual size_t write(WvBuf &inbuf, size_t count = INT_MAX) = 0;
00096 
00097     /**
00098      * Shuts down the reading side of the stream.
00099      * Subsequent calls to read() will fail.
00100      */
00101     virtual void noread() = 0;
00102 
00103     /**
00104      * Shuts down the writing side of the stream.
00105      * Subsequent calls to write() will fail.
00106      */
00107     virtual void nowrite() = 0;
00108     
00109     /** Returns true if the stream is readable. */
00110     virtual bool isreadable() = 0;
00111     
00112     /** Returns true if the stream is writable (without using the outbuf). */
00113     virtual bool iswritable() = 0;
00114     
00115     /**
00116      * flush the output buffer, if we can do it without delaying more than
00117      * msec_timeout milliseconds at a time.  (-1 means wait forever)
00118      * 
00119      * Returns true if it finished flushing (ie. the outbuf is empty).
00120      * 
00121      * FIXME: Something like this probably belongs in IWvStream, but
00122      * probably not exactly this.
00123      */
00124     virtual bool flush(time_t msec_timeout) = 0;
00125 
00126     /**
00127      * Returns true if we want to flush the output buffer right now.  This
00128      * allows us to implement delayed_flush(), flush_then_close(), etc, but
00129      * it's still super-ugly and probably needs to go away.  (In fact, all
00130      * our buffer flushing is super-ugly right now.)
00131      */
00132     virtual bool should_flush() = 0;
00133 
00134     /** Sets a callback to be invoked on close().  */
00135     virtual void setclosecallback(WvStreamCallback _callfunc,
00136                                   void *_userdata) = 0;
00137     
00138     // IObject
00139     static const XUUID XIID;
00140 };
00141 
00142 DEFINE_XIID(IWvStream, {0x7ca76e98, 0xb653, 0x43d7,
00143     {0xb0, 0x56, 0x8b, 0x9d, 0xde, 0x9a, 0xbe, 0x9d}});
00144 
00145 /**
00146  * Unified support for streams, that is, sequences of bytes that may or
00147  * may not be ready for read/write at any given time.
00148  * 
00149  * We provide typical read and write routines, as well as a select() function
00150  * for each stream.
00151  */
00152 class WvStream : public GenericComponent<IWvStream>
00153 {
00154 public:
00155     /**
00156      * 'force' is the list of default SelectRequest values when you use the
00157      * variant of select() that doesn't override them.
00158      */
00159     SelectRequest force;
00160     
00161     /**
00162      * If this is set, select() doesn't return true for read unless the
00163      * given stream also returns true for write.
00164      */
00165     WvStream *read_requires_writable;
00166 
00167     /**
00168      * If this is set, select() doesn't return true for write unless the
00169      * given stream also returns true for read.
00170      */
00171     WvStream *write_requires_readable;
00172     
00173     /** If this is set, enables the use of continue_select(). */
00174     bool uses_continue_select;
00175 
00176     /** Specifies the stack size to reserve for continue_select(). */
00177     size_t personal_stack_size;
00178 
00179     /**
00180      * This will be true during callback execution if the
00181      * callback was triggered by the alarm going off.
00182      */
00183     bool alarm_was_ticking;
00184     
00185     /** Basic constructor for just a do-nothing WvStream */
00186     WvStream();
00187     virtual ~WvStream();
00188 
00189     /**
00190      * Close the stream if it is open; isok() becomes false from now on.
00191      * Note!!  If you override this function in a derived class, you must
00192      *   call it yourself from your destructor.  WvStream::~WvStream()
00193      *   can only call WvStream::close() because of the way virtual
00194      *   functions work in C++.
00195      */ 
00196     virtual void close();
00197 
00198     /** Override seterr() from WvError so that it auto-closes the stream. */
00199     virtual void seterr(int _errnum);
00200     void seterr(WvStringParm specialerr)
00201         { WvError::seterr(specialerr); }
00202     void seterr(WVSTRING_FORMAT_DECL)
00203         { seterr(WvString(WVSTRING_FORMAT_CALL)); }
00204     
00205     /** return true if the stream is actually usable right now */
00206     virtual bool isok() const;
00207     
00208     /** read a data block on the stream.  Returns the actual amount read. */
00209     virtual size_t read(void *buf, size_t count);
00210 
00211     /**
00212      * Read exactly count bytes from the stream.
00213      *
00214      * Notes:
00215      *      must be using continue_select to use this function.
00216      *      if timeout strikes or !isok() before count bytes could be read,
00217      *          nothing is read and 0 is returned.
00218      *      resets queuemin to 0.
00219      * 
00220      * FIXME: yes, that means if the stream closes, continue_read might not
00221      * read the last bit of data.  You can use read() for that if you want.
00222      */
00223     virtual size_t continue_read(time_t wait_msec, void *buf, size_t count);
00224 
00225     /** Read exactly count bytes from the stream, using continue_select(). */
00226     virtual size_t continue_read(time_t wait_msec, WvBuf &outbuf,
00227                                  size_t count);
00228 
00229     /**
00230      * Reads up to 'count' bytes of data from the stream into the buffer.
00231      * Returns the actual amount read.
00232      *
00233      * If 'count' is greater than the amount of free space available
00234      * in the buffer, only reads at most that amount.  You should
00235      * specify a reasonable upper bound on how much data should
00236      * be read at once.
00237      */
00238     virtual size_t read(WvBuf &outbuf, size_t count);
00239 
00240     /** 
00241      * Puts data back into the stream's internal buffer.  We cheat so that
00242      * there's no restriction on how much (or what) data can be unread().
00243      * This is different from WvBuf::unget() (which is rather restrictive).
00244      */
00245     virtual void unread(WvBuf &outbuf, size_t count);
00246 
00247     /**
00248      * Write data to the stream.  Returns the actual amount written.
00249      * Since WvStream has an output buffer, it *always* successfully "writes"
00250      * the full amount (but you might have to flush the buffers later so it
00251      * actually gets sent).
00252      */
00253     virtual size_t write(const void *buf, size_t count);
00254 
00255     /**
00256      * Writes data to the stream from the given buffer.
00257      * Returns the actual amount written.
00258      *
00259      * If count is greater than the amount of data available in
00260      * the buffer, only writes at most that amount.
00261      */
00262     virtual size_t write(WvBuf &inbuf, size_t count = INT_MAX);
00263 
00264     /**
00265      * set the maximum size of outbuf, beyond which a call to write() will
00266      * return 0.  I need to do this for tape backups, since all I can do
00267      * is write to the loopback as fast as I can, which causes us to run 
00268      * out of memory and get SIGABRT'd.  (dcoombs: 12/15/2000)
00269      * 
00270      * FIXME: there must be a better way.  This confuses the semantics of
00271      * write(); can you trust it to always write all the bytes, or not?
00272      */
00273     void outbuf_limit(size_t size)
00274         { max_outbuf_size = size; }
00275 
00276     virtual void noread();
00277     virtual void nowrite();
00278     
00279     virtual bool isreadable();
00280     virtual bool iswritable();
00281     
00282     /**
00283      * unbuffered I/O functions; these ignore the buffer, which is
00284      * handled by read().  Don't call these functions explicitly unless
00285      * you have a _really_ good reason.
00286      * 
00287      * This is what you would override in a derived class.
00288      */ 
00289     virtual size_t uread(void *buf, size_t count)
00290         { return 0; /* basic WvStream doesn't actually do anything! */ }
00291 
00292     /**
00293      * unbuffered I/O functions; these ignore the buffer, which is
00294      * handled by write().  Don't call these functions explicitly unless
00295      * you have a _really_ good reason.
00296      * 
00297      * This is what you would override in a derived class.
00298      */ 
00299     virtual size_t uwrite(const void *buf, size_t count)
00300         { return 0; /* basic WvStream doesn't actually do anything! */ }
00301     
00302     /**
00303      * read up to one line of data from the stream and return a pointer
00304      * to the internal buffer containing this line.  If the end-of-line
00305      * 'separator' is encountered, it is removed from the string.  If
00306      * wait_msec times out before the end of line is found, returns NULL and
00307      * the line may be returned next time, or you can read what we have so
00308      * far by calling read().
00309      *
00310      * If wait_msec < 0, waits forever for a newline (often a bad idea!)
00311      * If wait_msec=0, never waits.  Otherwise, waits up to wait_msec
00312      * milliseconds until a newline appears.
00313      *
00314      * Readahead specifies the maximum amount of data that the stream is
00315      * allowed to read in one shot.
00316      *
00317      * It is expected that there will be no NULL characters on the line.
00318      * 
00319      * If uses_continue_select is true, getline() will use continue_select()
00320      * rather than select() to wait for its timeout.
00321      */
00322     char *getline(time_t wait_msec, char separator = '\n',
00323                   int readahead = 1024);
00324     
00325     /**
00326      * force read() to not return any bytes unless 'count' bytes can be
00327      * read at once.  (Useful for processing Content-Length headers, etc.)
00328      * Use count==0 to disable this feature.
00329      * 
00330      * WARNING: getline() sets queuemin to 0 automatically!
00331      */ 
00332     void queuemin(size_t count)
00333         { queue_min = count; }
00334 
00335     /**
00336      * drain the input buffer (read and discard data until select(0)
00337      * returns false)
00338      */
00339     void drain();
00340     
00341     /**
00342      * force write() to always buffer output.  This can be more efficient
00343      * if you write a lot of small segments and want to "coagulate" them
00344      * automatically.  To flush the output buffer, use flush() or select().
00345      */ 
00346     void delay_output(bool is_delayed)
00347     {
00348         outbuf_delayed_flush = is_delayed;
00349         want_to_flush = !is_delayed;
00350     }
00351 
00352     /**
00353      * if true, force write() to call flush() each time, the default behavour.
00354      * otherwise, flush() is granted special meaning when explicitly invoked
00355      * by the client and write() may empty the output buffer, but will not
00356      * explicitly flush().
00357      */
00358     void auto_flush(bool is_automatic)
00359         { is_auto_flush = is_automatic; }
00360 
00361     /**
00362      * flush the output buffer, if we can do it without delaying more than
00363      * msec_timeout milliseconds at a time.  (-1 means wait forever)
00364      * 
00365      * Returns true if the flushing finished (the output buffer is empty).
00366      */
00367     virtual bool flush(time_t msec_timeout);
00368 
00369     virtual bool should_flush();
00370 
00371     /**
00372      * flush the output buffer automatically as select() is called.  If
00373      * the buffer empties, close the stream.  If msec_timeout seconds pass,
00374      * close the stream.  After the stream closes, it will become !isok()
00375      * (and a WvStreamList can delete it automatically)
00376      */ 
00377     void flush_then_close(int msec_timeout);
00378     
00379     /**
00380      * pre_select() sets up for eventually calling ::select().
00381      * It adds the right fds to the read, write, and except lists in the
00382      * SelectInfo struct.
00383      * 
00384      * Returns true if we already know this stream is ready, and there's no
00385      * need to actually do a real ::select().  Some streams, such as timers,
00386      * can be implemented by _only_ either returning true or false here after
00387      * doing a calculation, and never actually adding anything to the
00388      * SelectInfo.
00389      * 
00390      * You can add your stream to any of the lists even if readable,
00391      * writable, or isexception isn't set.  This is what force_select()
00392      * does.  You can also choose not to add yourself to the list if you know
00393      * it would be useless right now.
00394      * 
00395      * pre_select() is only called if isok() is true.
00396      * 
00397      * pre_select() is allowed to reduce msec_timeout (or change it if it's
00398      * -1).  However, it's not allowed to _increase_ msec_timeout.
00399      */ 
00400     virtual bool pre_select(SelectInfo &si);
00401     
00402     /**
00403      * A more convenient version of pre_select() usable for overriding the
00404      * 'want' value temporarily.
00405      */
00406     bool pre_select(SelectInfo &si, const SelectRequest &r)
00407     {
00408         SelectRequest oldwant = si.wants;
00409         si.wants = r;
00410         bool val = pre_select(si);
00411         si.wants = oldwant;
00412         return val;
00413     }
00414     
00415     /**
00416      * Like pre_select(), but still exists even if you override the other
00417      * pre_select() in a subclass.  Sigh.
00418      */
00419     bool xpre_select(SelectInfo &si, const SelectRequest &r)
00420         { return pre_select(si, r); }
00421     
00422     /**
00423      * post_select() is called after ::select(), and returns true if this
00424      * object is now ready.  Usually this is done by checking for this object
00425      * in the read, write, and except lists in the SelectInfo structure.  If
00426      * you want to do it in some other way, you should usually do it in
00427      * pre_select() instead.
00428      * 
00429      * You may also want to do extra maintenance functions here; for example,
00430      * the standard WvStream::post_select tries to flush outbuf if it's
00431      * nonempty.  WvTCPConn might retry connect() if it's waiting for a
00432      * connection to be established.
00433      */
00434     virtual bool post_select(SelectInfo &si);
00435 
00436     /**
00437      * Like post_select(), but still exists even if you override the other
00438      * post_select() in a subclass.  Sigh.
00439      */
00440     bool xpost_select(SelectInfo &si, const SelectRequest &r)
00441         { return post_select(si, r); }
00442     
00443     /**
00444      * A more convenient version of post_select() usable for overriding the
00445      * 'want' value temporarily.
00446      */
00447     bool post_select(SelectInfo &si, const SelectRequest &r)
00448     {
00449         SelectRequest oldwant = si.wants;
00450         si.wants = r;
00451         bool val = post_select(si);
00452         si.wants = oldwant;
00453         return val;
00454     }
00455     
00456     /**
00457      * Return true if any of the requested features are true on the stream.
00458      * If msec_timeout < 0, waits forever (bad idea!).  ==0, does not wait.
00459      * Otherwise, waits for up to msec_timeout milliseconds.
00460      * 
00461      * **NOTE**
00462      *   select() is _not_ virtual!  To change the select() behaviour
00463      *   of a stream, override the pre_select() and/or post_select()
00464      *   functions.
00465      * 
00466      * This version of select() sets forceable==true, so force_select
00467      * options are taken into account.
00468      * 
00469      * You almost always use this version of select() with callbacks, like
00470      * this:  if (stream.select(1000)) stream.callback();
00471      * 
00472      * If you want to read/write the stream in question, try using the other
00473      * variant of select().
00474      * 
00475      * DEPRECATED.  Call runonce() instead.
00476      */
00477     bool select(time_t msec_timeout)
00478         { return _select(msec_timeout, false, false, false, true); }
00479     
00480     /**
00481      * Exactly the same as:
00482      *     if (select(timeout)) callback();
00483      * 
00484      * ...except that the above is deprecated, because it assumes callbacks
00485      * aren't called automatically and that the return value of one-parameter
00486      * select() is actually meaningful.
00487      * 
00488      * Update your main loop to call runonce() instead of the above.
00489      * 
00490      * Almost all modern programs should use msec_timeout = -1.
00491      */
00492     void runonce(time_t msec_timeout = -1)
00493         { if (select(msec_timeout)) callback(); }
00494     
00495      /**
00496       * This version of select() sets forceable==false, so we use the exact
00497       * readable/writable/isexception options provided.
00498       * 
00499       * You normally use this variant of select() when deciding whether you
00500       * should read/write a particular stream.  For example:
00501       * 
00502       *     if (stream.select(1000, true, false))
00503       *             len = stream.read(buf, sizeof(buf));
00504       * 
00505       * This variant of select() is probably not what you want with
00506       * most WvStreamLists, unless you know exactly what you're doing.
00507       * 
00508       * WARNING: the difference between the one-parameter and multi-parameter
00509       * versions of select() is *incredibly* confusing.  Make sure you use the
00510       * right one!
00511       * 
00512       * DEPRECATED.  Call isreadable() or iswritable() instead, if
00513       * msec_timeout was going to be zero.  Other values of msec_timeout are
00514       * not really recommended anyway.
00515       */
00516     bool select(time_t msec_timeout,
00517                 bool readable, bool writable, bool isex = false)
00518         { return _select(msec_timeout, readable, writable, isex, false); }
00519     
00520     /**
00521      * Use force_select() to force one or more particular modes (readable,
00522      * writable, or isexception) to true when selecting on this stream.
00523      * 
00524      * If an option is set 'true', we will select on that option when someone
00525      * does a select().  If it's set 'false', we don't change its force
00526      * status.  (To de-force something, use undo_force_select().)
00527      */
00528     void force_select(bool readable, bool writable, bool isexception = false);
00529     
00530     /**
00531      * Undo a previous force_select() - ie. un-forces the options which
00532      * are 'true', and leaves the false ones alone.
00533      */
00534     void undo_force_select(bool readable, bool writable,
00535                            bool isexception = false);
00536     
00537     /**
00538      * return to the caller from execute(), but don't really return exactly;
00539      * this uses WvTaskMan::yield() to return to the caller of callback()
00540      * without losing our place in execute() itself.  So, next time someone
00541      * calls callback(), it will be as if continue_select() returned.
00542      * 
00543      * NOTE: execute() will won't be called recursively this way, but any
00544      * other member function might get called, or member variables changed,
00545      * or the state of the world updated while continue_select() runs.  Don't
00546      * assume that nothing has changed after a call to continue_select().
00547      * 
00548      * NOTE 2: if you're going to call continue_select(), you should set
00549      * uses_continue_select=true before the first call to callback().
00550      * Otherwise your WvTask struct won't get created.
00551      * 
00552      * NOTE 3: if msec_timeout >= 0, this uses WvStream::alarm().
00553      */
00554     bool continue_select(time_t msec_timeout);
00555     
00556     /**
00557      * you MUST run this from your destructor if you use continue_select(), or
00558      * very weird things will happen if someone deletes your object while in
00559      * continue_select().
00560      */
00561     void terminate_continue_select();
00562 
00563     /**
00564      * get the remote address from which the last data block was received.
00565      * May be NULL.  The pointer becomes invalid upon the next call to read().
00566      */
00567     virtual const WvAddr *src() const;
00568     
00569     /**
00570      * define the callback function for this stream, called whenever
00571      * the callback() member is run, and passed the 'userdata' pointer.
00572      */
00573     void setcallback(WvStreamCallback _callfunc, void *_userdata)
00574         { callfunc = _callfunc; userdata = _userdata; }
00575         
00576     /** Sets a callback to be invoked on close().  */
00577     void setclosecallback(WvStreamCallback _callfunc, void *_userdata)
00578        { closecb_func = _callfunc; closecb_data = _userdata; }
00579 
00580     /**
00581      * set the callback function for this stream to an internal routine
00582      * that auto-forwards all incoming stream data to the given output
00583      * stream.
00584      */
00585     void autoforward(WvStream &s);
00586 
00587     /** Stops autoforwarding. */
00588     void noautoforward();
00589     static void autoforward_callback(WvStream &s, void *userdata);
00590     
00591     /**
00592      * if the stream has a callback function defined, call it now.
00593      * otherwise call execute().
00594      */
00595     virtual void callback();
00596     
00597     /**
00598      * set an alarm, ie. select() will return true after this many ms.
00599      * The alarm is cleared when callback() is called.
00600      */
00601     void alarm(time_t msec_timeout);
00602 
00603     /**
00604      * return the number of milliseconds remaining before the alarm will go
00605      * off; -1 means no alarm is set (infinity), 0 means the alarm has
00606      * been hit and will be cleared by the next callback().
00607      */
00608     time_t alarm_remaining();
00609 
00610     /**
00611      * print a preformatted WvString to the stream.
00612      * see the simple version of write() way up above.
00613      */
00614     size_t write(WvStringParm s)
00615         { return write(s.cstr(), s.len()); }
00616     size_t print(WvStringParm s)
00617         { return write(s); }
00618     size_t operator() (WvStringParm s)
00619         { return write(s); }
00620 
00621     /** preformat and write() a string. */
00622     size_t print(WVSTRING_FORMAT_DECL)
00623         { return write(WvString(WVSTRING_FORMAT_CALL)); }
00624     size_t operator() (WVSTRING_FORMAT_DECL)
00625         { return write(WvString(WVSTRING_FORMAT_CALL)); }
00626 
00627 protected:
00628     // builds the SelectInfo data structure (runs pre_select)
00629     // returns true if there are callbacks to be dispatched
00630     //
00631     // all of the fields are filled in with new values
00632     // si.msec_timeout contains the time until the next alarm expires
00633     bool _build_selectinfo(SelectInfo &si, time_t msec_timeout,
00634         bool readable, bool writable, bool isexcept,
00635         bool forceable);
00636 
00637     // runs the actual select() function over the given
00638     // SelectInfo data structure, returns the number of descriptors
00639     // in the set, and sets the error code if a problem occurs
00640     int _do_select(SelectInfo &si);
00641 
00642     // processes the SelectInfo data structure (runs post_select)
00643     // returns true if there are callbacks to be dispatched
00644     bool _process_selectinfo(SelectInfo &si, bool forceable);
00645 
00646     // tries to empty the output buffer if the stream is writable
00647     // not quite the same as flush() since it merely empties the output
00648     // buffer asynchronously whereas flush() might have other semantics
00649     // also handles autoclose (eg. after flush)
00650     bool flush_outbuf(time_t msec_timeout);
00651 
00652     // called once flush() has emptied outbuf to ensure that any other
00653     // internal stream buffers actually do get flushed before it returns
00654     virtual bool flush_internal(time_t msec_timeout);
00655     
00656     // the real implementations for these are actually in WvFDStream, which
00657     // is where they belong.  By IWvStream needs them to exist for now, so
00658     // it's a hack.  In standard WvStream they return -1.
00659     virtual int getrfd() const;
00660     virtual int getwfd() const;
00661     
00662 private:
00663     /** The function that does the actual work of select(). */
00664     bool _select(time_t msec_timeout,
00665                  bool readable, bool writable, bool isexcept,
00666                  bool forceable);
00667 
00668 
00669 protected:
00670     WvTaskMan *taskman;
00671 
00672     WvDynBuf inbuf, outbuf;
00673     WvStreamCallback callfunc;
00674     WvStreamCallback closecb_func;
00675     void *userdata;
00676     void *closecb_data;
00677     size_t max_outbuf_size;
00678     bool outbuf_delayed_flush;
00679     bool is_auto_flush;
00680     bool want_nowrite;
00681 
00682     // Used to guard against excessive flushing when using delay_flush
00683     bool want_to_flush;
00684 
00685     // Used to ensure we don't flush recursively.
00686     bool is_flushing;
00687 
00688     size_t queue_min;           // minimum bytes to read()
00689     time_t autoclose_time;      // close eventually, even if output is queued
00690     WvTime alarm_time;          // select() returns true at this time
00691     WvTime last_alarm_check;    // last time we checked the alarm_remaining
00692     bool running_callback;      // already in the callback() function
00693     bool wvstream_execute_called;
00694     
00695     WvTask *task;
00696 
00697     /** Prevent accidental copying of WvStreams. */
00698     WvStream(const WvStream &s) { }
00699     WvStream& operator= (const WvStream &s) { return *this; }
00700 
00701     /**
00702      * actually do the callback for an arbitrary stream.
00703      * This is a static function so we can pass it as a function pointer
00704      * to WvTask functions.
00705      */
00706     static void _callback(void *stream);
00707     
00708     /**
00709      * The callback() function calls execute(), and then calls the user-
00710      * specified callback if one is defined.  Do not call execute() directly;
00711      * call callback() instead.
00712      * 
00713      * The default execute() function does nothing.
00714      * 
00715      * Note: If you override this function in a derived class, you must
00716      * call the parent execute() yourself from the derived class.
00717      */
00718     virtual void execute();
00719     
00720     // every call to select() selects on the globalstream.
00721     static WvStream *globalstream;
00722 };
00723 
00724 /**
00725  * Console streams...
00726  *
00727  * This can be reassigned while the program is running, if desired,
00728  * but MUST NOT be NULL.
00729  */
00730 extern WvStream *wvcon; // tied stdin and stdout stream
00731 extern WvStream *wvin;  // stdin stream
00732 extern WvStream *wvout; // stdout stream
00733 extern WvStream *wverr; // stderr stream
00734 
00735 #endif // __WVSTREAM_H

Generated on Sat Feb 21 21:05:32 2004 for WvStreams by doxygen 1.3.5