Main Page Namespace List Class Hierarchy Alphabetical List Compound List File List Namespace Members Compound Members File Members

strmod::strmod::StreamFDModule Class Reference

This module is for communicating outside your program via UNIX IO. More...

#include <StrMod/StreamFDModule.h>

Inheritance diagram for strmod::strmod::StreamFDModule:

[legend]List of all members.


Public Types
typedef lcore::enum_set< ErrorType, ErrRead, ErrFatal >	ErrorSet
	Typedef for set of error types.
enum	IOCheckFlags { CheckNone, CheckRead, CheckWrite, CheckBoth }
	What directions is IO checked in? This is used for file descriptors that are open only for reading, or only for writing. More...
enum	ErrorType { ErrRead, ErrWrite, ErrGeneral, ErrFatal }
	What kinds of errors are possible? More...
Public Methods
	StreamFDModule (int fd, unievent::Dispatcher &disp, unievent::UnixEventRegistry &ureg, IOCheckFlags checkmask=CheckBoth)
	Constructs a StreamFDModule from an OS file descriptor.
virtual	~StreamFDModule ()
	Closes the associated file descriptor.
virtual int	AreYouA (const lcore::ClassIdent &cid) const
	Asks if a class is of a particular type, or publicly derived from that type.
virtual bool	canCreate (int side) const
	Can a plug be created on the given side?
virtual bool	ownsPlug (const Plug *p) const
	Does the module own this plug?
virtual bool	deletePlug (Plug *p)
	Please delete this plug.
bool	hasErrorIn (ErrorType err) const throw ()
	Check for an error in the given category.
bool	hasErrorIn (const ErrorSet &set) const throw ()
	Check for an error in one of the categories given by the set.
void	onErrorIn (ErrorType err, const unievent::EventPtr &ev) throw ()
	Ask to post an event when the given error type happens.
void	resetErrorIn (ErrorType err) throw ()
	Reset the error value for a particular category.
const unievent::UNIXError &	getErrorIn (ErrorType err) const throw ()
	Get the error value for a particular category.
void	setSendChunkOnEOF (bool newval) throw ()
	Set whether or not and EOFStrChunk is sent when an EOF is read.
bool	getSendChunkOnEOF () throw ()
	Does this module send a chunk on EOF?
void	setMaxChunkSize (size_t mbs)
	Sets the maximum block size to be read in a single read operation.
size_t	getMaxChunkSize () const
	Returns the maximum block size to be read in a single read operation.
size_t	getBestChunkSize () const
	This returns the optimal IO blocksize for this descriptor.
void	setMaxToBest ()
	Mostly equivalent to setMaxChunkSize(BestChunkSize()) If the value returned by BestChunkSize is an 'unreasonable' value such as less than 1024 (1k) bytes, or more than 65536 (64k) bytes, the value is set to the closest 'reasonable' value.
Static Public Attributes
const STR_ClassIdent	identifier
	A unique identifier for this class.
const size_t	S_max_bytes_without_dispatch = 256U * 1024U
	This is the maximum number of bytes to read or write without going back to the dispatcher.
Protected Methods
virtual const lcore::ClassIdent *	i_GetIdent () const
	Returns the class identifier for the class the object actually is.
virtual Plug *	i_MakePlug (int side)
	Makes a plug on the given side.
virtual void	plugWrite (const StrChunkPtr &ptr)
	Called by FPlug::i_Write.
virtual const StrChunkPtr	plugRead ()
	Called by FPlug::i_Read.
virtual void	doReadFD ()
	Read from fd into buffed_read_.
virtual void	doWriteFD ()
	Write to fd from cur_write_, using the info in write_vec_.
virtual void	writeEOF ()
	An EOF indication has been written.
void	setErrorIn (ErrorType err, const unievent::UNIXError &errval)
	Set an error in a particular category.
void	eventRead ()
	Called by readev_ and resumeread_'s triggerEvent.
void	eventWrite ()
	Called by writeev_ and resumewrite_'s triggerEvent.
void	eventError ()
	Called by errorev_'s triggerEvent.
void	eventResumeRead ()
	Called by resumeread_'s triggerEvent.
void	eventResumeWrite ()
	Called by resumewrite_'s triggerEvent.
int	getFD () const throw ()
	Get the file descriptor so a derived class can do something to it.
Friends
class	FPlug
class	StreamFDModule::EvMixin
class	StreamFDModule::FDPollRdEv
class	StreamFDModule::FDPollWrEv
class	StreamFDModule::FDPollErEv
class	StreamFDModule::ResumeReadEv
class	StreamFDModule::ResumeWriteEv
class	MyPollEvent

Detailed Description

This module is for communicating outside your program via UNIX IO.

One side of this module is a UNIX file descriptor, and the other side is the plug. Everything written to the plug is written to the file descriptor, and everything read from the file descriptor is read from the plug.

There are (or will be) ways of asking for events to be posted when stuff happens that the StreamFDModule can't deal with directly, such has EOF, read or write errors, or unexpected file descriptor closings.

Definition at line 65 of file StreamFDModule.h.

Member Enumeration Documentation

enum strmod::strmod::StreamFDModule::ErrorType

What kinds of errors are possible?

Enumeration values:

ErrRead Error while reading, might have read an EOF. Must be lowest enum value.

ErrWrite Error while writing, might have written an EOF.

ErrGeneral General error affecting both reading and writing.

ErrFatal General, fatal error affecting both reading and writing. Must be highest enum value.

Definition at line 98 of file StreamFDModule.h.

enum strmod::strmod::StreamFDModule::IOCheckFlags

What directions is IO checked in? This is used for file descriptors that are open only for reading, or only for writing.

Enumeration values:

CheckNone Don't bother with checking for reading or writing.

CheckRead Only check file descriptor for reading.

CheckWrite Only check file descriptor for writing.

CheckBoth Check file descriptor for reading and writing.

Definition at line 90 of file StreamFDModule.h.

Constructor & Destructor Documentation

strmod::strmod::StreamFDModule::StreamFDModule ( int fd,

unievent::Dispatcher & disp,

unievent::UnixEventRegistry & ureg,

IOCheckFlags checkmask = CheckBoth

)

Constructs a StreamFDModule from an OS file descriptor.

Parameters:

fd The file descriptor to attach to.

disp The strmod::unievent::Dispatcher to use for posting an event to when it becomes apparent that this module is in danger of hogging the CPU.

ureg The strmod::unievent::UnixEventRegistry to use to register to recieve file descriptor events. A reference to the event registry is kept until object destruction. The StreamFDModule doesn't 'own' the registry.

checkmask Describes what kinds of IO that can be done (and therefore, should be checked for) on fd.

Definition at line 798 of file StreamFDModule.cxx.

Member Function Documentation

int strmod::strmod::StreamFDModule::AreYouA ( const lcore::ClassIdent & cid ) const [inline, virtual]

Asks if a class is of a particular type, or publicly derived from that type.
Overriden in every derived class (with a static identifier member) to compare against the identifier, then call the AreYouA methods of all the superclasses.

Parameters:

cid Usually <class>::identifier for the class you want to ask if the object is an instance of.

Reimplemented from strmod::strmod::StreamModule.
Definition at line 323 of file StreamFDModule.h.

bool strmod::strmod::StreamFDModule::deletePlug ( Plug * p ) [inline, virtual]

Please delete this plug.
Modules are supposed to own plugs, so you aren't supposed to delete them yourself.
Returns false on failure. Failure could happen because module does not own the plug.
Implements strmod::strmod::StreamModule.
Definition at line 338 of file StreamFDModule.h.

void strmod::strmod::StreamFDModule::doReadFD ( ) [protected, virtual]

Read from fd into buffed_read_.
Assumes that buffed_read_ is empty, that there are no read errors, no fatal errors, and that EOF has not been read.
If the read returns '0' and the EOF on read flag (flags_.chunkeof, possibly set by setSendChunkOnEOF() ) is set, buffed_read_ will contain an EOFStrChunk.
Definition at line 596 of file StreamFDModule.cxx.

void strmod::strmod::StreamFDModule::doWriteFD ( ) [protected, virtual]

Write to fd from cur_write_, using the info in write_vec_.
Assumes that cur_write_ isn't empty, that there are no write errors, no fatal errors, and that EOF has not been written.
If cur_write_ is an EOFStrChunk, it will call writeEOF().
Definition at line 685 of file StreamFDModule.cxx.

size_t strmod::strmod::StreamFDModule::getBestChunkSize ( ) const

This returns the optimal IO blocksize for this descriptor.
This returns the st_blksize member of the stat structure returned by fstat'ing the file descriptor. If the stat cannot be performed, or st_blksize is 0, a default value (most likely 4096) is returned.
In a certain special case, if 0 < st_blksize < 64, 64 is returned.
Definition at line 469 of file StreamFDModule.cxx.

virtual const lcore::ClassIdent* strmod::strmod::StreamFDModule::i_GetIdent ( ) const [inline, protected, virtual]

Returns the class identifier for the class the object actually is.
Should always be overridden in any class that has a static identifier member.
Reimplemented from strmod::strmod::StreamModule.
Definition at line 233 of file StreamFDModule.h.

StreamModule::Plug * strmod::strmod::StreamFDModule::i_MakePlug ( int side ) [inline, protected, virtual]

Makes a plug on the given side.
Guaranteed to never be called if canCreate would return false. Must NEVER return 0 (NULL).
Implements strmod::strmod::StreamModule.
Definition at line 367 of file StreamFDModule.h.

void strmod::strmod::StreamFDModule::onErrorIn ( ErrorType err,

const unievent::EventPtr & ev

) throw ()

Ask to post an event when the given error type happens.
Currently only one event per error type is allowed. If there is already an event for a particular error type, that event will be forgotten about and not posted.
Definition at line 378 of file StreamFDModule.cxx.

void strmod::strmod::StreamFDModule::resetErrorIn ( ErrorType err ) throw ()

Reset the error value for a particular category.
This does not work for the ErrFatal category.
Definition at line 384 of file StreamFDModule.cxx.

void strmod::strmod::StreamFDModule::writeEOF ( ) [protected, virtual]

An EOF indication has been written.
This function has to handle it. This function follows the template method pattern from Design Patterns.
Do whatever is needed to write an EOF to the file descriptor for this module.
Definition at line 777 of file StreamFDModule.cxx.

Member Data Documentation

const size_t strmod::strmod::StreamFDModule::S_max_bytes_without_dispatch = 256U * 1024U [static]

This is the maximum number of bytes to read or write without going back to the dispatcher.
If the socket on this class has enough data going through it to saturate the CPU, the StreamFDModule may never give the CPU to any of the other StreamFDModules unless it voluntarily gives it up after passing a certain amount of data. This is the constant that determines how much data is enough.
This should possibly be a configurable value, but it isn't yet. If it is too low, you call back the dispatcher too often, and high bandwidth connections are handled slightly less efficiently than they could be. If it's too high you'll get choppy response. It's kinda like the multitasking timeslice value in an OS.
Definition at line 124 of file StreamFDModule.h.

The documentation for this class was generated from the following files:

Generated on Wed Jan 29 00:32:55 2003 for libNet by

1.3-rc1

strmod::strmod::StreamFDModule Class Reference

Public Types

Public Methods

Static Public Attributes

Protected Methods

Friends

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation