ola::io::PollerInterface Class Reference

Detailed Description

The interface for the Poller classes.

This forms the basis for the low level event management. The SelectServer will add / remove descriptors as required and then call Poll() with a timeout. The Poll() method is responsible for checking for timeouts (via the TimeoutManager) and then blocking until the descriptors are ready or a timeout event occurs. This blocking is done with select(), poll(), epoll() or kevent(), depending on the implementation.

Once the blocking wait returns. any ready descriptors should the appropriate method called: ola::io::ReadFileDescriptor::PerformRead(), ola::io::WriteFileDescriptor::PerformWrite() or the callback set in ola::io::ConnectedDescriptor::SetOnClose(). Once all descriptors and any new timeouts have been handled, Poll() returns.

Warning

It's absolutely critical that implementations of PollerInterface be reentrant. Calling any of the read / write / close actions may in turn add / remove descriptors, including the descriptor the method was itself called on. There are tests in SelectServerTest.cpp to exercise some of these cases but implementors need to be careful.

For example, if Poll() iterates over a set of Descriptors and calls PerformRead() when appropriate, the RemoveReadDescriptor() method can not simply call erase on the set, since doing so would invalidate the iterator held in Poll(). The solution is to either use a data structure that does not invalidate iterators on erase or use a double-lookup and set the pointer to NULL to indicate erasure.

It's also important to realize that after a RemoveReadDescriptor() or RemoveWriteDescriptor() is called, neither the FD number nor the pointer to the Destructor can be used again as a unique identifier. This is because either may be reused immediately following the call to remove.

Inheritance diagram for ola::io::PollerInterface:

Public Member Functions
virtual	~PollerInterface ()
	Destructor.
virtual bool	AddReadDescriptor (ReadFileDescriptor *descriptor)=0
	Register a ReadFileDescriptor for read events. More...
virtual bool	AddReadDescriptor (ConnectedDescriptor *descriptor, bool delete_on_close)=0
	Register a ConnectedDescriptor for read events. More...
virtual bool	RemoveReadDescriptor (ReadFileDescriptor *descriptor)=0
	Unregister a ReadFileDescriptor for read events. More...
virtual bool	RemoveReadDescriptor (ConnectedDescriptor *descriptor)=0
	Unregister a ConnectedDescriptor for read events. More...
virtual bool	AddWriteDescriptor (WriteFileDescriptor *descriptor)=0
	Register a WriteFileDescriptor to receive ready-to-write events. More...
virtual bool	RemoveWriteDescriptor (WriteFileDescriptor *descriptor)=0
	Unregister a WriteFileDescriptor for write events. More...
virtual const TimeStamp *	WakeUpTime () const =0
virtual bool	Poll (TimeoutManager *timeout_manager, const TimeInterval &poll_interval)=0
	Poll the Descriptors for events and execute any callbacks. More...

Static Public Attributes
static const char	K_READ_DESCRIPTOR_VAR [] = "ss-read-descriptors"
	The number of descriptors registered for read events.
static const char	K_WRITE_DESCRIPTOR_VAR [] = "ss-write-descriptor"
	The number of descriptors registered for write events.
static const char	K_CONNECTED_DESCRIPTORS_VAR []
	The number of connected descriptors registered for read events. More...

Static Protected Attributes
static const char	K_LOOP_TIME [] = "ss-loop-time"
	The time spent in the event loop.
static const char	K_LOOP_COUNT [] = "ss-loop-count"
	The number of iterations through the event loop.

Member Function Documentation

AddReadDescriptor() [1/2]

virtual bool ola::io::PollerInterface::AddReadDescriptor ( ReadFileDescriptor *  descriptor )

pure virtual

Register a ReadFileDescriptor for read events.

Parameters

descriptor

the ReadFileDescriptor to register. The OnData() method will be called when there is data available for reading.

Returns

true if the descriptor was registered, false otherwise.

Implemented in ola::io::EPoller, ola::io::KQueuePoller, ola::io::WindowsPoller, and ola::io::SelectPoller.

AddReadDescriptor() [2/2]

virtual bool ola::io::PollerInterface::AddReadDescriptor ( ConnectedDescriptor *  descriptor, bool  delete_on_close  )

pure virtual

Register a ConnectedDescriptor for read events.

Parameters

descriptor	the ConnectedDescriptor to register. The OnData() method will be called when there is data available for reading. Additionally, OnClose() will be called if the other end closes the connection.
delete_on_close	controls whether the descriptor is deleted when it's closed.

Returns

true if the descriptor was registered, false otherwise.

Implemented in ola::io::EPoller, ola::io::KQueuePoller, ola::io::WindowsPoller, and ola::io::SelectPoller.

AddWriteDescriptor()

virtual bool ola::io::PollerInterface::AddWriteDescriptor ( WriteFileDescriptor *  descriptor )

pure virtual

Register a WriteFileDescriptor to receive ready-to-write events.

Parameters

descriptor

the WriteFileDescriptor to register. The PerformWrite() method will be called when the descriptor is ready for writing.

Returns

true if the descriptor was registered, false otherwise.

Implemented in ola::io::EPoller, ola::io::KQueuePoller, ola::io::WindowsPoller, and ola::io::SelectPoller.

Poll()

virtual bool ola::io::PollerInterface::Poll ( TimeoutManager *  timeout_manager, const TimeInterval &  poll_interval  )

pure virtual

Poll the Descriptors for events and execute any callbacks.

Parameters

timeout_manager	the TimeoutManager to use for timer events.
poll_interval	the maximum time to block for.

Returns

false if any errors occurred, true if events were handled.

Implemented in ola::io::EPoller, ola::io::KQueuePoller, ola::io::WindowsPoller, and ola::io::SelectPoller.

RemoveReadDescriptor() [1/2]

virtual bool ola::io::PollerInterface::RemoveReadDescriptor ( ReadFileDescriptor *  descriptor )

pure virtual

Unregister a ReadFileDescriptor for read events.

Parameters

descriptor

the ReadFileDescriptor to unregister.

Returns

true if unregistered successfully, false otherwise.

Precondition

descriptor->ReadFileDescriptor() is valid.

Implemented in ola::io::EPoller, ola::io::KQueuePoller, ola::io::WindowsPoller, and ola::io::SelectPoller.

RemoveReadDescriptor() [2/2]

virtual bool ola::io::PollerInterface::RemoveReadDescriptor ( ConnectedDescriptor *  descriptor )

pure virtual

Unregister a ConnectedDescriptor for read events.

Parameters

descriptor

the ConnectedDescriptor to unregister.

Returns

true if unregistered successfully, false otherwise.

Precondition

descriptor->ReadFileDescriptor() is valid.

Implemented in ola::io::EPoller, ola::io::KQueuePoller, ola::io::WindowsPoller, and ola::io::SelectPoller.

RemoveWriteDescriptor()

virtual bool ola::io::PollerInterface::RemoveWriteDescriptor ( WriteFileDescriptor *  descriptor )

pure virtual

Unregister a WriteFileDescriptor for write events.

Parameters

descriptor

the WriteFileDescriptor to unregister.

Returns

true if unregistered successfully, false otherwise.

Precondition

descriptor->WriteFileDescriptor() is valid.

Implemented in ola::io::EPoller, ola::io::KQueuePoller, ola::io::WindowsPoller, and ola::io::SelectPoller.

Member Data Documentation

K_CONNECTED_DESCRIPTORS_VAR

const char ola::io::PollerInterface::K_CONNECTED_DESCRIPTORS_VAR

static

Initial value:

=
    "ss-connected-descriptors"

The number of connected descriptors registered for read events.

---

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

• common/io/PollerInterface.h
• common/io/PollerInterface.cpp