lat::IOSelector Class Reference

Multi-strategy I/O channel listener. More...

#include <Iguana/Utilities/classlib/iobase/IOSelector.h>

List of all members.

Public Types

enum Strategy {
S_DEFAULT, S_SELECT, S_RTSIGIO, S_RTSIGONE,
S_DEVPOLL, S_POLL, S_KQUEUE
}

Selector strategies. More...

Public Member Functions

virtual void andMask (IOChannel *channel, unsigned value)

virtual void attach (IOChannel *channel, unsigned mask, IOSelectCB c=IOSelectCB())

virtual void clear (void)

virtual void detach (IOChannel *channel)

virtual unsigned dispatch (long msecs=-1)

IOSelector (const Strategy *strategy=SV_DEFAULT)

virtual bool nextReady (IOSelectEvent &event, IOSelectCB &c)

virtual void orMask (IOChannel *channel, unsigned value)

virtual unsigned pump (long msecs=-1)

virtual void setMask (IOChannel *channel, unsigned value)

virtual bool wait (long msecs=-1)

virtual ~IOSelector (void)

Static Public Attributes

static CLASSLIB_API const Strategy SV_DEFAULT []

Default strategy vector.

static CLASSLIB_API const Strategy SV_HIGHPERF []

Default high-load strategy vector.

Private Attributes

IOSelectMethod * m_strategy

Detailed Description

Multi-strategy I/O channel listener.

IOSelector is a class for listening changes in the status of multiple I/O channels simultaneously. It is intended to be used when an application has multiple I/O channels whose activity it wants to monitor and to whose states it wants to respond to. Typical uses include server applications that want to wait and respond to client activity, or clients that have more than one server to talk to.

IOSelector defines a basic platform-specific strategy for listening activity on the channels (S_DEFAULT), sufficient for most basic needs. Applications with more specific demands, such as very large number of clients or high performance requirements can customise the selector to particular platform-specific system calls.

The general usage model of this class is to first attach one or more IOChannel objects, perform a wait, respond to the updated channel states, perform further waits, and finally deregister the channels. Channels can be added or removed at any time (FIXME: will changes erase current wait update status?).

It is more efficient to register channels once and do multiple waits on them than to register them all, do one wait and then register all again. While channels can be added and removed at any time that suits the application, changing the list as rarely as possible enables significant optimisation with some strategies (e.g. S_DEVPOLL). Clients that can sustain descriptor interest for a long time should use dispatch(). Since pump() always removes the descriptor before invoking the handler, it is by definition not able to sustain high performance, but may still suit certain I/O processing models.

If the application needs to maintain connection to more than just a handful of clients, it is in general better to use this class than to use several threads with blocking I/O. (FIXME: explain why or at least link to the documentation.)

Limitations:

It is not possible to attach() the same channel several times.

Selecting on the same I/O channel in multiple threads may not work on all systems and may cause unpredictable results on the systems where it works. It will cause major havoc on Windows.

The client should always be prepared to get (FIXME: EWOULDBLOCK) when operating on a channel even if the selector has marked it active for I/O. (FIXME: Explain why.) Obviously the clients can make no assumptions on how much I/O is possible with the channel unless they have guarantees from some other source. In general most clients are best modeled as state machines.

Most unix platforms cannot select on files, they will always be reported ready. Some signal files available for use if the file pointer is not at the end of the file. Windows in theory can, but this implementation simulates the unix behaviour for coherency. On some systems IOChannel::transfer() provides high-throughput operations that bypass cycling of channel contents via memory, for example it may be possible to send file contents directly to a socket. Another possibility is to use asynchronous I/O.

For a descriptor selected for urgent data (out-of-band socket data), urgent trigger does not mean the client will be able to read the urgent data -- the read attempt may block or throw EWOULDBLOCK error. The client may first have to read ordinary data to make room in system buffers for the out-of-band data, or perform other tricks. For examples on correct handling of such conditions, including use of Socket::isAtMark(), see GNU libc info, node "Out-of-Band Data".

Windows has only limited ability to listen to I/O handles and heterogeneous list of handles in particular. There is better support for asynchronous multi-threaded I/O, somewhat similar to POSIX AIO, a rather different and potentially more complicated design paradigm. This library works around most of the Windows limitations, but may spawn hidden threads to do its job. (FIXME: Can overlapped I/O (posix aio) or I/O completion ports (posix aio completion routines notifying a thread pool that uses lifo semantics) be combined with this meaningfully?)

(FIXME: Explain how this meshes with asynchronous i/o (posix aio, w32 overlapped i/o). Explain the issues with w32, especially for handles obtained from outside sources and the limitations on simultaneous usage of handle vs. select.

Definition at line 109 of file IOSelector.h.

Member Enumeration Documentation

enum lat::IOSelector::Strategy

Selector strategies.

Enumerator:

S_DEFAULT	Default selector strategy, should always be included as a last-resort fallback if other methods are unavailable. On unix: select() with automatic switch to poll() if there are too many file descriptors (FIXME not yet, sometimes poll() is just a wrapper for select()). On windows a multi-threaded custom poller; the only alternative on this platform.
S_SELECT	Use select().
S_RTSIGIO	Use real-time signals (real-time version of SIGIO) with POSIX signal queueing. Automatically uses S_POLL as fallback for handling overflow.
S_RTSIGONE	S_RTSIGIO with only one signal queued per file descriptor which can significantly reduce overflow.
S_DEVPOLL	Use /dev/poll.
S_POLL	Use poll().
S_KQUEUE	Use kqueue().

Definition at line 113 of file IOSelector.h.

00113                   {
00120         S_DEFAULT,
00121 
00123         S_SELECT,
00124 
00128         S_RTSIGIO,
00129 
00132         S_RTSIGONE,
00133 
00135         S_DEVPOLL,
00136 
00138         S_POLL,
00139 
00141         S_KQUEUE
00142     };

Constructor & Destructor Documentation

lat::IOSelector::IOSelector ( const Strategy * strategy = SV_DEFAULT )

virtual lat::IOSelector::~IOSelector ( void ) [virtual]

Member Function Documentation

virtual void lat::IOSelector::andMask	(	IOChannel *	channel,
		unsigned	value
	)			`[virtual]`

virtual void lat::IOSelector::attach	(	IOChannel *	channel,
		unsigned	mask,
		IOSelectCB	c = `IOSelectCB()`
	)			`[virtual]`

Referenced by DQMNet::DQMNet(), IgNet::IgNet(), DQMNet::onPeerConnect(), IgNet::onPeerConnect(), VisNet::onPeerConnect(), VisNet::run(), IgNet::run(), DQMNet::run(), DQMNet::startLocalServer(), VisNet::startLocalServer(), IgNet::startLocalServer(), and VisNet::VisNet().

virtual void lat::IOSelector::clear ( void ) [virtual]

virtual void lat::IOSelector::detach ( IOChannel * channel ) [virtual]

Referenced by IgNet::losePeer(), DQMNet::losePeer(), and VisNet::losePeer().

virtual unsigned lat::IOSelector::dispatch ( long msecs = -1 ) [virtual]

Referenced by VisNet::run(), IgNet::run(), and DQMNet::run().

virtual bool lat::IOSelector::nextReady	(	IOSelectEvent &	event,
		IOSelectCB &	c
	)			`[virtual]`

virtual void lat::IOSelector::orMask	(	IOChannel *	channel,
		unsigned	value
	)			`[virtual]`

virtual unsigned lat::IOSelector::pump ( long msecs = -1 ) [virtual]

virtual void lat::IOSelector::setMask	(	IOChannel *	channel,
		unsigned	value
	)			`[virtual]`

Referenced by VisNet::onPeerData(), DQMNet::onPeerData(), IgNet::onPeerData(), IgNet::updateMask(), VisNet::updateMask(), and DQMNet::updateMask().

virtual bool lat::IOSelector::wait ( long msecs = -1 ) [virtual]

Member Data Documentation

IOSelectMethod* lat::IOSelector::m_strategy [private]

Definition at line 204 of file IOSelector.h.

CLASSLIB_API const Strategy lat::IOSelector::SV_DEFAULT[] [static]

Default strategy vector.

Definition at line 145 of file IOSelector.h.

CLASSLIB_API const Strategy lat::IOSelector::SV_HIGHPERF[] [static]

Default high-load strategy vector.

Definition at line 148 of file IOSelector.h.

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

Iguana/Utilities/classlib/iobase/IOSelector.h

Generated on Tue Jun 9 18:48:26 2009 for CMSSW by

1.5.4


Public Types
enum	Strategy { S_DEFAULT, S_SELECT, S_RTSIGIO, S_RTSIGONE, S_DEVPOLL, S_POLL, S_KQUEUE }
	Selector strategies. More...
Public Member Functions
virtual void	andMask (IOChannel *channel, unsigned value)
virtual void	attach (IOChannel *channel, unsigned mask, IOSelectCB c=IOSelectCB())
virtual void	clear (void)
virtual void	detach (IOChannel *channel)
virtual unsigned	dispatch (long msecs=-1)
	IOSelector (const Strategy *strategy=SV_DEFAULT)
virtual bool	nextReady (IOSelectEvent &event, IOSelectCB &c)
virtual void	orMask (IOChannel *channel, unsigned value)
virtual unsigned	pump (long msecs=-1)
virtual void	setMask (IOChannel *channel, unsigned value)
virtual bool	wait (long msecs=-1)
virtual	~IOSelector (void)
Static Public Attributes
static CLASSLIB_API const Strategy	SV_DEFAULT []
	Default strategy vector.
static CLASSLIB_API const Strategy	SV_HIGHPERF []
	Default high-load strategy vector.
Private Attributes
IOSelectMethod *	m_strategy