Detailed Description

A single threaded I/O event management system.

SelectServer is the core of the event driven system. It's responsible for invoking Callbacks when certain events occur.

Example: The following snippet shows how a SelectServer can be used with a listening UDP socket. The ReceiveMessage function will be called whenever there is new data on the UDP socket.

#include <ola/Logging.h>
#include <ola/base/Array.h>
#include <ola/io/SelectServer.h>
#include <ola/network/Socket.h>
#include <ola/network/SocketAddress.h>
using ola::network::IPV4Address;
using ola::network::IPV4SocketAddress;
using ola::network::UDPSocket;
// The port to listen on.
static const unsigned int PORT = 12345;
// Called when a UDP datagram arrives.
void ReceiveMessage(UDPSocket *socket) {
  ola::network::IPV4SocketAddress client;
  uint8_t data[1500];
  ssize_t data_size = arraysize(data);
  if (socket->RecvFrom(data, &data_size, &client)) {
    OLA_INFO << "Received " << data_size << " bytes from " << client;
  } else {
    OLA_WARN << "Recv failure";
  }
}
int main() {
  ola::InitLogging(ola::OLA_LOG_INFO, ola::OLA_LOG_STDERR);
  IPV4SocketAddress listen_address(IPV4Address::WildCard(), PORT);
  UDPSocket udp_socket;
  if (!udp_socket.Init()) {
    return -1;
  }
  if (!udp_socket.Bind(listen_address)) {
    return -1;
  }
  udp_socket.SetOnData(ola::NewCallback(&ReceiveMessage, &udp_socket));
  ola::io::SelectServer ss;
  ss.AddReadDescriptor(&udp_socket);
  ss.Run();
}

The SelectServer has a number of different implementations depending on the platform. On systems with epoll, the flag --no-use-epoll will disable the use of epoll(), reverting to select(). The PollerInterface defines the contract between the SelectServer and the lower level, platform dependent Poller classes.

All methods except Execute() and Terminate() must be called from the thread that Run() was called in.

Inheritance diagram for ola::io::SelectServer:

[legend]

Collaboration diagram for ola::io::SelectServer:

[legend]

Classes
struct	Options

Public Member Functions
	SelectServer (ola::ExportMap export_map=NULL, Clock clock=NULL)
	Create a new SelectServer. More...

	SelectServer (const Options &options)
	Create a new SelectServer. More...

	~SelectServer ()
	Clean up. More...

bool	IsRunning () const
	Checks if the SelectServer is running. More...

const TimeStamp *	WakeUpTime () const
	The time when this SelectServer was woken up. More...

void	Terminate ()
	Exit from the Run() loop. More...

void	SetDefaultInterval (const TimeInterval &block_interval)
	Set the duration to block for. More...

void	Run ()
	Enter the event loop. More...

void	RunOnce ()
	Do a single pass through the event loop. Does not block.

void	RunOnce (const TimeInterval &block_interval)
	Do a single pass through the event loop. More...

bool	AddReadDescriptor (ReadFileDescriptor *descriptor)
	Register a ReadFileDescriptor for read-events. More...

bool	AddReadDescriptor (ConnectedDescriptor *descriptor, bool delete_on_close=false)
	Register a ConnectedDescriptor for read-events. More...

void	RemoveReadDescriptor (ReadFileDescriptor *descriptor)
	Remove a ReadFileDescriptor for read-events. More...

void	RemoveReadDescriptor (ConnectedDescriptor *descriptor)
	Remove a ConnectedDescriptor for read-events. More...

bool	AddWriteDescriptor (WriteFileDescriptor *descriptor)
	Register a WriteFileDescriptor for write-events. More...

void	RemoveWriteDescriptor (WriteFileDescriptor *descriptor)
	Remove a WriteFileDescriptor for write-events. More...

ola::thread::timeout_id	RegisterRepeatingTimeout (unsigned int ms, ola::Callback0< bool > *callback)
	Execute a callback periodically. More...

ola::thread::timeout_id	RegisterRepeatingTimeout (const ola::TimeInterval &interval, ola::Callback0< bool > *callback)
	Execute a callback periodically. More...

ola::thread::timeout_id	RegisterSingleTimeout (unsigned int ms, ola::SingleUseCallback0< void > *callback)
	Execute a callback after a certain time interval. More...

ola::thread::timeout_id	RegisterSingleTimeout (const ola::TimeInterval &interval, ola::SingleUseCallback0< void > *callback)
	Execute a callback after a certain time interval. More...

void	RemoveTimeout (ola::thread::timeout_id id)
	Cancel an existing timeout. More...

void	RunInLoop (ola::Callback0< void > *callback)
	Execute a callback on every event loop. More...

void	Execute (ola::BaseCallback0< void > *callback)
	Execute the supplied callback at some point in the future. More...

void	DrainCallbacks ()
	Run all callbacks until there are none left.

Friends
class	::SelectServerTest

Constructor & Destructor Documentation

◆ SelectServer() [1/2]

ola::io::SelectServer::SelectServer	(	ola::ExportMap *	export_map = `NULL`,
		Clock *	clock = `NULL`
	)

Create a new SelectServer.

Parameters

export_map	the ExportMap to use for stats
clock	the Clock to use to keep time.

◆ SelectServer() [2/2]

ola::io::SelectServer::SelectServer ( const Options & options )

explicit

Create a new SelectServer.

Parameters

options additional options.

◆ ~SelectServer()

ola::io::SelectServer::~SelectServer ( )

Clean up.

The SelectServer should be terminated before it's deleted.

Member Function Documentation

◆ AddReadDescriptor() [1/2]

bool ola::io::SelectServer::AddReadDescriptor ( ReadFileDescriptor * descriptor )

virtual

Register a ReadFileDescriptor for read-events.

Parameters

descriptor the ReadFileDescriptor to add.

Returns: true if the descriptor was added, false if the descriptor was previously added.

When the descriptor is ready for reading, PerformRead() will be called.

Implements ola::io::SelectServerInterface.

◆ AddReadDescriptor() [2/2]

bool ola::io::SelectServer::AddReadDescriptor	(	ConnectedDescriptor *	descriptor,
		bool	delete_on_close = `false`
	)

virtual

Register a ConnectedDescriptor for read-events.

Parameters

descriptor	the ConnectedDescriptor to add.
delete_on_close	if true, ownership of the ConnectedDescriptor is transferred to the SelectServer.

Returns: true if the descriptor was added, false if the descriptor was previously added.

When the descriptor is ready for reading, PerformRead() will be called. Prior to PerformRead(), IsClosed() is called. If this returns true, and delete_on_close was set, the descriptor will be deleted.

Implements ola::io::SelectServerInterface.

◆ AddWriteDescriptor()

bool ola::io::SelectServer::AddWriteDescriptor ( WriteFileDescriptor * descriptor )

virtual

Register a WriteFileDescriptor for write-events.

Parameters

descriptor the WriteFileDescriptor to add.

When the descriptor is writeable, PerformWrite() is called.

Implements ola::io::SelectServerInterface.

◆ Execute()

void ola::io::SelectServer::Execute ( ola::BaseCallback0< void > * callback )

virtual

Execute the supplied callback at some point in the future.

Parameters

callback the callback to run.

This method provides the following guarantees:

The callback will not be run immediately.
The callback will be run at some point in the future. That is, the callback will not leak. Any remaining pending callbacks will be run during the destruction of the class implementing ExecutorInterface.
For a given thread, callbacks will be run in the order in which they were added.

When queuing callbacks, you need to ensure that either:

The objects used in the callback outlive the ExecutorInterface
That the callback is run before the objects are deleted.

To achieve the latter it's common to keep track of the number of outstanding callbacks and then call DrainCallbacks() in the destructor if the number of outstanding callbacks is non-0.

Implements ola::thread::ExecutorInterface.

◆ IsRunning()

bool ola::io::SelectServer::IsRunning ( ) const

inline

Checks if the SelectServer is running.

Returns: true if the SelectServer is in the Run() method.

◆ RegisterRepeatingTimeout() [1/2]

timeout_id ola::io::SelectServer::RegisterRepeatingTimeout	(	unsigned int	period,
		ola::Callback0< bool > *	callback
	)

virtual

Execute a callback periodically.

Parameters

period	the number of milliseconds between each execution of the callback.
callback	the callback to run. Ownership is transferred.

Returns: a timeout_id which can be used later to cancel the timeout.

Deprecated:: Use the version that takes a TimeInterval instead.

Returning false from the callback will cause it to be cancelled.

Implements ola::io::SelectServerInterface.

◆ RegisterRepeatingTimeout() [2/2]

timeout_id ola::io::SelectServer::RegisterRepeatingTimeout	(	const ola::TimeInterval &	period,
		ola::Callback0< bool > *	callback
	)

virtual

Execute a callback periodically.

Parameters

period	the time interval between each execution of the callback.
callback	the callback to run. Ownership is transferred.

Returns: a timeout_id which can be used later to cancel the timeout.

Returning false from the callback will cause it to be cancelled.

Implements ola::io::SelectServerInterface.

◆ RegisterSingleTimeout() [1/2]

timeout_id ola::io::SelectServer::RegisterSingleTimeout	(	unsigned int	delay,
		ola::SingleUseCallback0< void > *	callback
	)

virtual

Execute a callback after a certain time interval.

Parameters

delay	the number of milliseconds before the callback is executed.
callback	the callback to run. Ownership is transferred.

Returns: a timeout_id which can be used later to cancel the timeout.

Deprecated:: Use the version that takes a TimeInterval instead.

Implements ola::io::SelectServerInterface.

◆ RegisterSingleTimeout() [2/2]

timeout_id ola::io::SelectServer::RegisterSingleTimeout	(	const ola::TimeInterval &	delay,
		ola::SingleUseCallback0< void > *	callback
	)

virtual

Execute a callback after a certain time interval.

Parameters

delay	the time interval to wait before the callback is executed.
callback	the callback to run. Ownership is transferred.

Returns: a timeout_id which can be used later to cancel the timeout.

Implements ola::io::SelectServerInterface.

◆ RemoveReadDescriptor() [1/2]

void ola::io::SelectServer::RemoveReadDescriptor ( ReadFileDescriptor * descriptor )

virtual

Remove a ReadFileDescriptor for read-events.

Parameters

descriptor the descriptor to remove.

Warning: Descriptors must be removed from the SelectServer before they are closed. Not doing so will result in hard to debug failures.

Implements ola::io::SelectServerInterface.

◆ RemoveReadDescriptor() [2/2]

void ola::io::SelectServer::RemoveReadDescriptor ( ConnectedDescriptor * descriptor )

virtual

Remove a ConnectedDescriptor for read-events.

Parameters

descriptor the descriptor to remove.

Warning: Descriptors must be removed from the SelectServer before they are closed. Not doing so will result in hard to debug failures.

Implements ola::io::SelectServerInterface.

◆ RemoveTimeout()

void ola::io::SelectServer::RemoveTimeout ( ola::thread::timeout_id id )

virtual

Cancel an existing timeout.

Parameters

id	the timeout_id returned by a call to RegisterRepeatingTimeout or RegisterSingleTimeout.

Implements ola::io::SelectServerInterface.

◆ RemoveWriteDescriptor()

void ola::io::SelectServer::RemoveWriteDescriptor ( WriteFileDescriptor * descriptor )

virtual

Remove a WriteFileDescriptor for write-events.

Parameters

descriptor the descriptor to remove.

Warning: Descriptors must be removed from the SelectServer before they are closed. Not doing so will result in hard to debug failures.

Implements ola::io::SelectServerInterface.

◆ Run()

void ola::io::SelectServer::Run ( )

Enter the event loop.

Run() will return once Terminate() has been called.

◆ RunInLoop()

void ola::io::SelectServer::RunInLoop ( ola::Callback0< void > * callback )

Execute a callback on every event loop.

Parameters

callback the Callback to execute. Ownership is transferrred to the SelectServer.

Be very cautious about using this, it's almost certainly not what you want.

There is no way to remove a Callback added with this method.

◆ RunOnce()

void ola::io::SelectServer::RunOnce ( const TimeInterval & block_interval )

Do a single pass through the event loop.

Parameters

block_interval The maximum time to block if there is no I/O or timer events.

◆ SetDefaultInterval()

void ola::io::SelectServer::SetDefaultInterval ( const TimeInterval & block_interval )

Set the duration to block for.

Parameters

block_interval the interval to block for.

This controls the upper bound on the duration between callbacks added with RunInLoop().

◆ Terminate()

void ola::io::SelectServer::Terminate ( )

Exit from the Run() loop.

Terminate() may be called from any thread.

◆ WakeUpTime()

const TimeStamp * ola::io::SelectServer::WakeUpTime ( ) const

virtual

The time when this SelectServer was woken up.

Returns: The TimeStamp of when the SelectServer was woken up.

If running within the same thread as the SelectServer, this is a efficient way to get the current time.

Implements ola::io::SelectServerInterface.

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

include/ola/io/SelectServer.h
common/io/SelectServer.cpp

Detailed Description

Classes

Public Member Functions

Friends

Constructor & Destructor Documentation

◆ SelectServer() [1/2]

◆ SelectServer() [2/2]

◆ ~SelectServer()

Member Function Documentation

◆ AddReadDescriptor() [1/2]

◆ AddReadDescriptor() [2/2]

◆ AddWriteDescriptor()

◆ Execute()

◆ IsRunning()

◆ RegisterRepeatingTimeout() [1/2]

◆ RegisterRepeatingTimeout() [2/2]

◆ RegisterSingleTimeout() [1/2]

◆ RegisterSingleTimeout() [2/2]

◆ RemoveReadDescriptor() [1/2]

◆ RemoveReadDescriptor() [2/2]

◆ RemoveTimeout()

◆ RemoveWriteDescriptor()

◆ Run()

◆ RunInLoop()

◆ RunOnce()

◆ SetDefaultInterval()

◆ Terminate()

◆ WakeUpTime()