Open Lighting Architecture: ola::io::PollerInterface Class Reference

| Open Lighting Architecture 0.10.9

Loading...
Searching...
No Matches
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:

## Public Member Functions
virtual | ~PollerInterface ()
| Destructor.
virtual bool | AddReadDescriptor (ReadFileDescriptor *descriptor)=0
| Register a ReadFileDescriptor for read events.
virtual bool | AddReadDescriptor (ConnectedDescriptor *descriptor, bool delete_on_close)=0
| Register a ConnectedDescriptor for read events.
virtual bool | RemoveReadDescriptor (ReadFileDescriptor *descriptor)=0
| Unregister a ReadFileDescriptor for read events.
virtual bool | RemoveReadDescriptor (ConnectedDescriptor *descriptor)=0
| Unregister a ConnectedDescriptor for read events.
virtual bool | AddWriteDescriptor (WriteFileDescriptor *descriptor)=0
| Register a WriteFileDescriptor to receive ready-to-write events.
virtual bool | RemoveWriteDescriptor (WriteFileDescriptor *descriptor)=0
| Unregister a WriteFileDescriptor for write events.
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.

## 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.

## 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 | ( | 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::SelectPoller, and ola::io::WindowsPoller.

## ◆ AddReadDescriptor() [2/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::SelectPoller, and ola::io::WindowsPoller.

## ◆ 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::SelectPoller, and ola::io::WindowsPoller.

## ◆ 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::SelectPoller, and ola::io::WindowsPoller.

## ◆ RemoveReadDescriptor() [1/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::SelectPoller, and ola::io::WindowsPoller.

## ◆ RemoveReadDescriptor() [2/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::SelectPoller, and ola::io::WindowsPoller.

## ◆ 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::SelectPoller, and ola::io::WindowsPoller.

## 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