Poco::Net

class SocketReactor

Library: Net
Package: Reactor
Header: Poco/Net/SocketReactor.h

Description

This class, which is part of the Reactor pattern, implements the "Initiation Dispatcher".

The Reactor pattern has been described in the book "Pattern Languages of Program Design" by Jim Coplien and Douglas C. Schmidt (Addison Wesley, 1995).

The Reactor design pattern handles service requests that are delivered concurrently to an application by one or more clients. Each service in an application may consist of several methods and is represented by a separate event handler. The event handler is responsible for servicing service-specific requests. The SocketReactor dispatches the event handlers.

Event handlers (any class can be an event handler - there is no base class for event handlers) can be registered with the addEventHandler() method and deregistered with the removeEventHandler() method.

An event handler is always registered for a certain socket, which is given in the call to addEventHandler(). Any method of the event handler class can be registered to handle the event - the only requirement is that the method takes a pointer to an instance of SocketNotification (or a subclass of it) as argument.

Once started, the SocketReactor waits for events on the registered sockets, using PollSet:poll(). If an event is detected, the corresponding event handler is invoked. There are five event types (and corresponding notification classes) defined: ReadableNotification, WritableNotification, ErrorNotification, TimeoutNotification and ShutdownNotification.

The ReadableNotification will be dispatched if a socket becomes readable. The WritableNotification will be dispatched if a socket becomes writable. The ErrorNotification will be dispatched if there is an error condition on a socket.

Timeout/sleep strategy operates as follows:

If the poll timeout expires and no event has occurred, a TimeoutNotification will be dispatched to all event handlers registered for it. This is done in the onTimeout() method which can be overridden by subclasses to perform custom timeout processing.

By default, the SocketReactor is configured to start sleeping when the poll timeout is zero and there are no socket events for a certain amount of time; sleep duration is progressive, up to the configured limit. This behavior can be disabled through configuration parameters.

When there are no registered handlers, the SocketRactor sleeps an incremental amount of milliseconds, up to the sleep limit. Increment step value and sleep limit are configurable.

Finally, when the SocketReactor is about to shut down (as a result of stop() being called), it dispatches a ShutdownNotification to all event handlers. This is done in the onShutdown() method which can be overridden by subclasses to perform custom shutdown processing.

The SocketReactor is implemented so that it can run in its own thread. Moreover, the thread affinity to a CPU core can optionally be set for the thread on platforms where that functionality is supported and implemented. It is also possible to run multiple SocketReactors in parallel, as long as they work on different sockets.

It is safe to call addEventHandler() and removeEventHandler() from another thread while the SocketReactor is running. Also, it is safe to call addEventHandler() and removeEventHandler() from event handlers.

SocketReactor uses NotificationCenter to notify observers. When a handler throws an exception, the NotificationCenter stops notifying the rest of the observers about that particular event instance and propagates the exception, which is eventually caught in the SocketReactor::run() method. This sequence of events is obviously not desirable and it is highly recommended that handlers wrap the code in try/catch and deal with all the exceptions internally, lest they disrupt the notification of the peers.

Inheritance

Direct Base Classes: Poco::Runnable

All Base Classes: Poco::Runnable

Member Summary

Member Functions: addEventHandler, dispatch, getErrorNotification, getHandlers, getParams, getPollSet, getReadableNotification, getShutdownNotification, getThreadAffinity, getTimeout, getTimeoutNotification, getWritableNotification, has, hasEventHandler, hasSocketHandlers, mustStop, onError, onShutdown, onTimeout, removeEventHandler, run, setTimeout, stop, wakeUp

Inherited Functions: run

Nested Classes

struct Params

Reactor parameters. more...

Types Aliases

EventHandlerMap protected

using EventHandlerMap = std::map < int, NotifierPtr >;

MutexType protected

using MutexType = Poco::FastMutex;

NotificationPtr protected

using NotificationPtr = Poco::AutoPtr < SocketNotification >;

NotifierPtr protected

using NotifierPtr = Poco::AutoPtr < SocketNotifier >;

ScopedLock protected

using ScopedLock = MutexType::ScopedLock;

Constructors

SocketReactor

SocketReactor();

Creates the SocketReactor.

SocketReactor

explicit SocketReactor(
    const Poco::Timespan & pollTimeout,
    int threadAffinity = - 1
);

Creates the SocketReactor, using the given poll timeout.

The threadAffinity argument, when non-negative, indicates on which CPU core should the run() method run. Nonexisting core or situation when this feature is not implemented are silently ignored and this argument has no effect in such scenarios.

SocketReactor

SocketReactor(
    const Params & params,
    int threadAffinity = - 1
);

Creates the SocketReactor, using the given parameters. The threadAffinity argument, when non-negative, indicates on which CPU core should the run() method run. Nonexisting core or situation when this feature is not implemented are silently ignored and this argument has no effect in such scenarios.

Destructor

~SocketReactor virtual

virtual ~SocketReactor();

Destroys the SocketReactor.

Member Functions

addEventHandler

void addEventHandler(
    const Socket & socket,
    const Poco::AbstractObserver & observer
);

Registers an event handler with the SocketReactor.

Usage: 

Poco::Observer<MyEventHandler, SocketNotification> obs(*this, &MyEventHandler::handleMyEvent);
reactor.addEventHandler(obs);

getTimeout inline

const Poco::Timespan & getTimeout() const;

Returns the timeout.

has inline

bool has(
    const Socket & socket
) const;

Returns true if socket is registered with this rector.

hasEventHandler

bool hasEventHandler(
    const Socket & socket,
    const Poco::AbstractObserver & observer
);

Returns true if the observer is registered with SocketReactor for the given socket.

removeEventHandler

void removeEventHandler(
    const Socket & socket,
    const Poco::AbstractObserver & observer
);

Unregisters an event handler with the SocketReactor.

Usage: 

Poco::Observer<MyEventHandler, SocketNotification> obs(*this, &MyEventHandler::handleMyEvent);
reactor.removeEventHandler(obs);

run virtual

virtual void run();

Runs the SocketReactor. The reactor will run until stop() is called (in a separate thread). Can be overriden by inheriting classes.

See also: Poco::Runnable::run()

setTimeout inline

void setTimeout(
    const Poco::Timespan & timeout
);

Sets the timeout.

If no socket event occurs for the given timeout interval, a timeout event is sent to all event listeners.

The default timeout is 250 milliseconds;

The timeout is passed to the PollSet::poll() method.

stop

void stop();

Stops the SocketReactor.

The reactor will be stopped when the next event (including a timeout event) occurs.

wakeUp

void wakeUp();

Wakes up idle reactor.

dispatch protected inline

void dispatch(
    const Socket & socket,
    SocketNotification * pNotification
);

Dispatches the given notification to all observers registered for the given socket.

dispatch protected

void dispatch(
    SocketNotification * pNotification
);

Dispatches the given notification to all observers.

getErrorNotification protected inline

Notification * getErrorNotification();

getHandlers protected inline

const EventHandlerMap & getHandlers() const;

getParams protected inline

const Params & getParams() const;

getPollSet protected inline

const PollSet & getPollSet() const;

getReadableNotification protected inline

Notification * getReadableNotification();

getShutdownNotification protected inline

Notification * getShutdownNotification();

getThreadAffinity protected inline

int getThreadAffinity() const;

getTimeoutNotification protected inline

Notification * getTimeoutNotification();

getWritableNotification protected inline

Notification * getWritableNotification();

hasSocketHandlers protected

bool hasSocketHandlers();

mustStop protected inline

const std::atomic < bool > & mustStop() const;

onError protected inline

void onError(
    const Socket & socket,
    int code,
    const std::string & description
);

Notifies all subscribers when the reactor loop throws an exception.

onError protected

void onError(
    int code,
    const std::string & description
);

Notifies all subscribers when the reactor loop throws an exception.

onShutdown protected virtual

virtual void onShutdown();

Called when the SocketReactor is about to terminate.

Can be overridden by subclasses. The default implementation dispatches the ShutdownNotification and thus should be called by overriding implementations.

onTimeout protected virtual

virtual void onTimeout();

Called if the timeout expires and no other events are available.

Can be overridden by subclasses. The default implementation dispatches the TimeoutNotification and thus should be called by overriding implementations.

POCO C++ Libraries 1.14.0-all
Copyright © 2024, Applied Informatics Software Engineering GmbH and Contributors