Main Page | Modules | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Class Members | File Members | Related Pages

WvUnixDGConn Class Reference

#include <wvunixdgsocket.h>

Inheritance diagram for WvUnixDGConn:

Inheritance graph
[legend]
List of all members.

Detailed Description

WvStream-based Unix datagram domain socket connection class that listens on filename.

The specified file should already exist before using this.


Public Member Functions

 WvUnixDGConn (WvStringParm filename)
virtual size_t uwrite (const void *buf, size_t count)
 unbuffered I/O functions; these ignore the buffer, which is handled by write().
virtual bool pre_select (SelectInfo &si)
 pre_select() sets up for eventually calling ::select().
bool pre_select (SelectInfo &si, const SelectRequest &r)
 A more convenient version of pre_select() usable for overriding the 'want' value temporarily.
virtual bool post_select (SelectInfo &si)
 post_select() is called after ::select(), and returns true if this object is now ready.
bool post_select (SelectInfo &si, const SelectRequest &r)
 A more convenient version of post_select() usable for overriding the 'want' value temporarily.
int getrfd () const
 Returns the Unix file descriptor for reading from this stream.
int getwfd () const
 Returns the Unix file descriptor for writing to this stream.
int getfd () const
 Returns the Unix file descriptor for reading and writing.
virtual void close ()
 Closes the file descriptors.
virtual bool isok () const
 return true if the stream is actually usable right now
virtual size_t uread (void *buf, size_t count)
 unbuffered I/O functions; these ignore the buffer, which is handled by read().
virtual void maybe_autoclose ()
virtual void seterr (int _errnum)
 Override seterr() from WvError so that it auto-closes the stream.
void seterr (WvStringParm specialerr)
void seterr (WVSTRING_FORMAT_DECL)
virtual size_t read (void *buf, size_t count)
 read a data block on the stream.
virtual size_t read (WvBuf &outbuf, size_t count)
 Reads up to 'count' bytes of data from the stream into the buffer.
virtual size_t continue_read (time_t wait_msec, void *buf, size_t count)
 Read exactly count bytes from the stream.
virtual size_t continue_read (time_t wait_msec, WvBuf &outbuf, size_t count)
 Read exactly count bytes from the stream, using continue_select().
virtual void unread (WvBuf &outbuf, size_t count)
 Puts data back into the stream's internal buffer.
virtual size_t write (const void *buf, size_t count)
 Write data to the stream.
virtual size_t write (WvBuf &inbuf, size_t count=INT_MAX)
 Writes data to the stream from the given buffer.
size_t write (WvStringParm s)
 print a preformatted WvString to the stream.
void outbuf_limit (size_t size)
 set the maximum size of outbuf, beyond which a call to write() will return 0.
virtual void noread ()
virtual void nowrite ()
virtual bool isreadable ()
virtual bool iswritable ()
char * getline (time_t wait_msec, char separator= '\n', int readahead=1024)
 read up to one line of data from the stream and return a pointer to the internal buffer containing this line.
size_t read_until (void *buf, size_t count, time_t wait_msec, char separator)
 read up to count characters into buf, up to and including the first instance of separator.
void queuemin (size_t count)
 force read() to not return any bytes unless 'count' bytes can be read at once.
void drain ()
 drain the input buffer (read and discard data until select(0) returns false)
void delay_output (bool is_delayed)
 force write() to always buffer output.
void auto_flush (bool is_automatic)
 if true, force write() to call flush() each time, the default behavour.
virtual bool flush (time_t msec_timeout)
 flush the output buffer, if we can do it without delaying more than msec_timeout milliseconds at a time.
virtual bool should_flush ()
void flush_then_close (int msec_timeout)
 flush the output buffer automatically as select() is called.
bool xpre_select (SelectInfo &si, const SelectRequest &r)
 Like pre_select(), but still exists even if you override the other pre_select() in a subclass.
bool xpost_select (SelectInfo &si, const SelectRequest &r)
 Like post_select(), but still exists even if you override the other post_select() in a subclass.
bool select (time_t msec_timeout)
 Return true if any of the requested features are true on the stream.
bool select (time_t msec_timeout, bool readable, bool writable, bool isex=false)
 This version of select() sets forceable==false, so we use the exact readable/writable/isexception options provided.
void runonce (time_t msec_timeout=-1)
 Exactly the same as: if (select(timeout)) callback();.
void force_select (bool readable, bool writable, bool isexception=false)
 Use force_select() to force one or more particular modes (readable, writable, or isexception) to true when selecting on this stream.
void undo_force_select (bool readable, bool writable, bool isexception=false)
 Undo a previous force_select() - ie.
bool continue_select (time_t msec_timeout)
 return to the caller from execute(), but don't really return exactly; this uses WvCont::yield() to return to the caller of callback() without losing our place in execute() itself.
void terminate_continue_select ()
 you MUST run this from your destructor if you use continue_select(), or very weird things will happen if someone deletes your object while in continue_select().
virtual const WvAddrsrc () const
 get the remote address from which the last data block was received.
void setcallback (WvStreamCallback _callfunc, void *_userdata)
 define the callback function for this stream, called whenever the callback() member is run, and passed the 'userdata' pointer.
void setclosecallback (WvStreamCallback _callfunc, void *_userdata)
 Sets a callback to be invoked on close().
void autoforward (WvStream &s)
 set the callback function for this stream to an internal routine that auto-forwards all incoming stream data to the given output stream.
void noautoforward ()
 Stops autoforwarding.
void * _callwrap (void *)
 A wrapper that's compatible with WvCont, but calls the "real" callback.
void _callback ()
 Actually call the registered callfunc and execute().
virtual void callback ()
 if the stream has a callback function defined, call it now.
void alarm (time_t msec_timeout)
 set an alarm, ie.
time_t alarm_remaining ()
 return the number of milliseconds remaining before the alarm will go off; -1 means no alarm is set (infinity), 0 means the alarm has been hit and will be cleared by the next callback().
size_t print (WvStringParm s)
size_t print (WVSTRING_FORMAT_DECL)
 preformat and write() a string.
size_t operator() (WvStringParm s)
size_t operator() (WVSTRING_FORMAT_DECL)

Static Public Member Functions

static void autoforward_callback (WvStream &s, void *userdata)

Public Attributes

SelectRequest force
 'force' is the list of default SelectRequest values when you use the variant of select() that doesn't override them.
WvStreamread_requires_writable
 If this is set, select() doesn't return true for read unless the given stream also returns true for write.
WvStreamwrite_requires_readable
 If this is set, select() doesn't return true for write unless the given stream also returns true for read.
bool uses_continue_select
 If this is set, enables the use of continue_select().
size_t personal_stack_size
 Specifies the stack size to reserve for continue_select().
bool alarm_was_ticking
 This will be true during callback execution if the callback was triggered by the alarm going off.
bool stop_read
 True if noread()/nowrite()/close() have been called, respectively.
bool stop_write
 True if noread()/nowrite()/close() have been called, respectively.
bool closed
 True if noread()/nowrite()/close() have been called, respectively.

Protected Member Functions

void setfd (int fd)
 Sets the file descriptor for both reading and writing.
bool _build_selectinfo (SelectInfo &si, time_t msec_timeout, bool readable, bool writable, bool isexcept, bool forceable)
int _do_select (SelectInfo &si)
bool _process_selectinfo (SelectInfo &si, bool forceable)
bool flush_outbuf (time_t msec_timeout)
virtual bool flush_internal (time_t msec_timeout)
virtual void execute ()
 The callback() function calls execute(), and then calls the user- specified callback if one is defined.

Protected Attributes

WvString socketfile
int rfd
 The file descriptor for reading.
int wfd
 The file descriptor for writing.
bool shutdown_read
 Have we actually shut down the read/write sides?
bool shutdown_write
 Have we actually shut down the read/write sides?
WvDynBuf inbuf
WvDynBuf outbuf
WvStreamCallback callfunc
WvStreamCallback closecb_func
WvCallback< void *, void * > call_ctx
void * userdata
void * closecb_data
size_t max_outbuf_size
bool outbuf_delayed_flush
bool is_auto_flush
bool want_to_flush
bool is_flushing
size_t queue_min
time_t autoclose_time
WvTime alarm_time
WvTime last_alarm_check
bool wvstream_execute_called

Static Protected Attributes

static WvStreamglobalstream = NULL


Member Function Documentation

size_t WvUnixDGSocket::uwrite const void *  buf,
size_t  count
[virtual, inherited]
 

unbuffered I/O functions; these ignore the buffer, which is handled by write().

Don't call these functions explicitly unless you have a _really_ good reason.

This is what you would override in a derived class.

Reimplemented from WvFdStream.

bool WvUnixDGSocket::pre_select SelectInfo &  si  )  [virtual, inherited]
 

pre_select() sets up for eventually calling ::select().

It adds the right fds to the read, write, and except lists in the SelectInfo struct.

Returns true if we already know this stream is ready, and there's no need to actually do a real ::select(). Some streams, such as timers, can be implemented by _only_ either returning true or false here after doing a calculation, and never actually adding anything to the SelectInfo.

You can add your stream to any of the lists even if readable, writable, or isexception isn't set. This is what force_select() does. You can also choose not to add yourself to the list if you know it would be useless right now.

pre_select() is only called if isok() is true.

pre_select() is allowed to reduce msec_timeout (or change it if it's -1). However, it's not allowed to _increase_ msec_timeout.

Reimplemented from WvFdStream.

bool WvUnixDGSocket::post_select SelectInfo &  si  )  [virtual, inherited]
 

post_select() is called after ::select(), and returns true if this object is now ready.

Usually this is done by checking for this object in the read, write, and except lists in the SelectInfo structure. If you want to do it in some other way, you should usually do it in pre_select() instead.

You may also want to do extra maintenance functions here; for example, the standard WvStream::post_select tries to flush outbuf if it's nonempty. WvTCPConn might retry connect() if it's waiting for a connection to be established.

Reimplemented from WvFdStream.

void WvFdStream::setfd int  fd  )  [inline, protected, inherited]
 

Sets the file descriptor for both reading and writing.

Convenience method.

int WvFdStream::getrfd  )  const [inline, virtual, inherited]
 

Returns the Unix file descriptor for reading from this stream.

Returns: the file descriptor, or -1 if none

Reimplemented from WvStream.

int WvFdStream::getwfd  )  const [inline, virtual, inherited]
 

Returns the Unix file descriptor for writing to this stream.

Returns: the file descriptor, or -1 if none

Reimplemented from WvStream.

int WvFdStream::getfd  )  const [inline, inherited]
 

Returns the Unix file descriptor for reading and writing.

Asserts that the file descriptors for reading and writing are the same before returning.

Returns: the file descriptor, or -1 if none

void WvFdStream::close  )  [virtual, inherited]
 

Closes the file descriptors.

If it is undesirable for the file descriptors to be closed by this stream, duplicate the file descriptors using dup() before creating the stream.

Reimplemented from WvStream.

Reimplemented in WvModemBase, WvModem, WvTCPListener, and WvUnixListener.

size_t WvFdStream::uread void *  buf,
size_t  count
[virtual, inherited]
 

unbuffered I/O functions; these ignore the buffer, which is handled by read().

Don't call these functions explicitly unless you have a _really_ good reason.

This is what you would override in a derived class.

Reimplemented from WvStream.

Reimplemented in WvIPRawStream, WvTCPListener, WvUDPStream, WvUnixListener, and WvFileWatcher.

size_t WvStream::read void *  buf,
size_t  count
[virtual, inherited]
 

read a data block on the stream.

Returns the actual amount read.

size_t WvStream::read WvBuf outbuf,
size_t  count
[virtual, inherited]
 

Reads up to 'count' bytes of data from the stream into the buffer.

Returns the actual amount read.

If 'count' is greater than the amount of free space available in the buffer, only reads at most that amount. You should specify a reasonable upper bound on how much data should be read at once.

size_t WvStream::continue_read time_t  wait_msec,
void *  buf,
size_t  count
[virtual, inherited]
 

Read exactly count bytes from the stream.

Notes: must be using continue_select to use this function. if timeout strikes or !isok() before count bytes could be read, nothing is read and 0 is returned. resets queuemin to 0.

FIXME: yes, that means if the stream closes, continue_read might not read the last bit of data. You can use read() for that if you want.

void WvStream::unread WvBuf outbuf,
size_t  count
[virtual, inherited]
 

Puts data back into the stream's internal buffer.

We cheat so that there's no restriction on how much (or what) data can be unread(). This is different from WvBuf::unget() (which is rather restrictive).

size_t WvStream::write const void *  buf,
size_t  count
[virtual, inherited]
 

Write data to the stream.

Returns the actual amount written. Since WvStream has an output buffer, it *always* successfully "writes" the full amount (but you might have to flush the buffers later so it actually gets sent).

size_t WvStream::write WvBuf inbuf,
size_t  count = INT_MAX
[virtual, inherited]
 

Writes data to the stream from the given buffer.

Returns the actual amount written.

If count is greater than the amount of data available in the buffer, only writes at most that amount.

size_t WvStream::write WvStringParm  s  )  [inline, inherited]
 

print a preformatted WvString to the stream.

see the simple version of write() way up above.

void WvStream::outbuf_limit size_t  size  )  [inline, inherited]
 

set the maximum size of outbuf, beyond which a call to write() will return 0.

I need to do this for tape backups, since all I can do is write to the loopback as fast as I can, which causes us to run out of memory and get SIGABRT'd. (dcoombs: 12/15/2000)

FIXME: there must be a better way. This confuses the semantics of write(); can you trust it to always write all the bytes, or not?

char * WvStream::getline time_t  wait_msec,
char  separator = '\n',
int  readahead = 1024
[inherited]
 

read up to one line of data from the stream and return a pointer to the internal buffer containing this line.

If the end-of-line 'separator' is encountered, it is removed from the string. If wait_msec times out before the end of line is found, returns NULL and the line may be returned next time, or you can read what we have so far by calling read().

If wait_msec < 0, waits forever for a newline (often a bad idea!) If wait_msec=0, never waits. Otherwise, waits up to wait_msec milliseconds until a newline appears.

Readahead specifies the maximum amount of data that the stream is allowed to read in one shot.

It is expected that there will be no NULL characters on the line.

If uses_continue_select is true, getline() will use continue_select() rather than select() to wait for its timeout.

size_t WvStream::read_until void *  buf,
size_t  count,
time_t  wait_msec,
char  separator
[inherited]
 

read up to count characters into buf, up to and including the first instance of separator.

if separator is not found on input before timeout (usual symantics) or stream close or error, or if count is 0, nothing is placed in buf and 0 is returned.

if your buffer is not large enough for line, call multiple times until seperator is found at end of buffer to retrieve the entire line.

Returns the number of characters that were put in buf.

If uses_continue_select is true, getline() will use continue_select() rather than select() to wait for its timeout.

void WvStream::queuemin size_t  count  )  [inline, inherited]
 

force read() to not return any bytes unless 'count' bytes can be read at once.

(Useful for processing Content-Length headers, etc.) Use count==0 to disable this feature.

WARNING: getline() sets queuemin to 0 automatically!

void WvStream::delay_output bool  is_delayed  )  [inline, inherited]
 

force write() to always buffer output.

This can be more efficient if you write a lot of small segments and want to "coagulate" them automatically. To flush the output buffer, use flush() or select().

void WvStream::auto_flush bool  is_automatic  )  [inline, inherited]
 

if true, force write() to call flush() each time, the default behavour.

otherwise, flush() is granted special meaning when explicitly invoked by the client and write() may empty the output buffer, but will not explicitly flush().

bool WvStream::flush time_t  msec_timeout  )  [virtual, inherited]
 

flush the output buffer, if we can do it without delaying more than msec_timeout milliseconds at a time.

(-1 means wait forever)

Returns true if the flushing finished (the output buffer is empty).

void WvStream::flush_then_close int  msec_timeout  )  [inherited]
 

flush the output buffer automatically as select() is called.

If the buffer empties, close the stream. If msec_timeout seconds pass, close the stream. After the stream closes, it will become !isok() (and a WvStreamList can delete it automatically)

bool WvStream::xpre_select SelectInfo &  si,
const SelectRequest &  r
[inline, inherited]
 

Like pre_select(), but still exists even if you override the other pre_select() in a subclass.

Sigh.

bool WvStream::xpost_select SelectInfo &  si,
const SelectRequest &  r
[inline, inherited]
 

Like post_select(), but still exists even if you override the other post_select() in a subclass.

Sigh.

bool WvStream::select time_t  msec_timeout  )  [inline, inherited]
 

Return true if any of the requested features are true on the stream.

If msec_timeout < 0, waits forever (bad idea!). ==0, does not wait. Otherwise, waits for up to msec_timeout milliseconds.

**NOTE** select() is _not_ virtual! To change the select() behaviour of a stream, override the pre_select() and/or post_select() functions.

This version of select() sets forceable==true, so force_select options are taken into account.

You almost always use this version of select() with callbacks, like this: if (stream.select(1000)) stream.callback();

If you want to read/write the stream in question, try using the other variant of select().

DEPRECATED. Call runonce() instead.

bool WvStream::select time_t  msec_timeout,
bool  readable,
bool  writable,
bool  isex = false
[inline, inherited]
 

This version of select() sets forceable==false, so we use the exact readable/writable/isexception options provided.

You normally use this variant of select() when deciding whether you should read/write a particular stream. For example:

if (stream.select(1000, true, false)) len = stream.read(buf, sizeof(buf));

This variant of select() is probably not what you want with most WvStreamLists, unless you know exactly what you're doing.

WARNING: the difference between the one-parameter and multi-parameter versions of select() is *incredibly* confusing. Make sure you use the right one!

DEPRECATED. Call isreadable() or iswritable() instead, if msec_timeout was going to be zero. Other values of msec_timeout are not really recommended anyway.

void WvStream::runonce time_t  msec_timeout = -1  )  [inline, inherited]
 

Exactly the same as: if (select(timeout)) callback();.

...except that the above is deprecated, because it assumes callbacks aren't called automatically and that the return value of one-parameter select() is actually meaningful.

Update your main loop to call runonce() instead of the above.

Almost all modern programs should use msec_timeout = -1.

void WvStream::force_select bool  readable,
bool  writable,
bool  isexception = false
[inherited]
 

Use force_select() to force one or more particular modes (readable, writable, or isexception) to true when selecting on this stream.

If an option is set 'true', we will select on that option when someone does a select(). If it's set 'false', we don't change its force status. (To de-force something, use undo_force_select().)

void WvStream::undo_force_select bool  readable,
bool  writable,
bool  isexception = false
[inherited]
 

Undo a previous force_select() - ie.

un-forces the options which are 'true', and leaves the false ones alone.

bool WvStream::continue_select time_t  msec_timeout  )  [inherited]
 

return to the caller from execute(), but don't really return exactly; this uses WvCont::yield() to return to the caller of callback() without losing our place in execute() itself.

So, next time someone calls callback(), it will be as if continue_select() returned.

NOTE: execute() will won't be called recursively this way, but any other member function might get called, or member variables changed, or the state of the world updated while continue_select() runs. Don't assume that nothing has changed after a call to continue_select().

NOTE 2: if you're going to call continue_select(), you should set uses_continue_select=true before the first call to callback(). Otherwise your WvCont won't get created.

NOTE 3: if msec_timeout >= 0, this uses WvStream::alarm().

const WvAddr * WvStream::src  )  const [virtual, inherited]
 

get the remote address from which the last data block was received.

May be NULL. The pointer becomes invalid upon the next call to read().

Reimplemented in WvIPRawStream, WvStreamClone, WvTCPConn, WvTCPListener, WvUDPStream, WvUnixConn, and WvUnixListener.

void WvStream::callback  )  [virtual, inherited]
 

if the stream has a callback function defined, call it now.

otherwise call execute().

void WvStream::alarm time_t  msec_timeout  )  [inherited]
 

set an alarm, ie.

select() will return true after this many ms. The alarm is cleared when callback() is called.

void WvStream::execute  )  [protected, virtual, inherited]
 

The callback() function calls execute(), and then calls the user- specified callback if one is defined.

Do not call execute() directly; call callback() instead.

The default execute() function does nothing.

Note: If you override this function in a derived class, you must call the parent execute() yourself from the derived class.

Reimplemented in UniConfDaemonConn, WvDailyEvent, WvIStreamList, WvProtoStream, WvStreamClone, WvTimeoutStream, and WvTimeStream.


The documentation for this class was generated from the following file:
Generated on Sun Jul 10 16:30:55 2005 for WvStreams by  doxygen 1.4.0