Open Lighting Architecture  Latest Git
Public Member Functions | Static Public Attributes | Static Protected Attributes | List of all members
ola::io::PollerInterface Class Referenceabstract

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:
Inheritance graph
[legend]

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 TimeStampWakeUpTime () 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
descriptorthe 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
descriptorthe 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_closecontrols 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
descriptorthe 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_managerthe TimeoutManager to use for timer events.
poll_intervalthe 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
descriptorthe 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
descriptorthe 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
descriptorthe 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: