<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>Class Poco::Net::SocketReactor</title> <meta http-equiv="content-type" content="text/html; charset=utf-8"/> <meta name="author" content="Applied Informatics Software Engineering GmbH and Contributors"/> <meta name="publisher" content="Applied Informatics Software Engineering GmbH and Contributors"/> <meta name="copyright" content="Copyright (c) 2009, Applied Informatics Software Engineering GmbH and Contributors"/> <meta name="language" content="en"/> <meta name="date" content="2009-11-24"/> <meta name="generator" content="PocoDoc"/> <link rel="stylesheet" href="css/styles.css" type="text/css"/> </head> <body bgcolor="#ffffff" leftmargin="0" topmargin="0"> <div class="header"> <h1 class="namespace"><a href="Poco.Net.html" class="namespace">Poco::Net</a></h1> <h1 class="symbol">class SocketReactor</h1> </div> <div class="body"> <p> <b>Library:</b> Net<br /> <b>Package:</b> Reactor<br /> <b>Header:</b> Poco/Net/SocketReactor.h</p> <h2>Description</h2> <div class="description"> <p>This class, which is part of the Reactor pattern, implements the "Initiation Dispatcher". </p> <p>The Reactor pattern has been described in the book "Pattern Languages of Program Design" by Jim Coplien and Douglas C. Schmidt (Addison Wesley, 1995). </p> <p>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 <a href="Poco.Net.SocketReactor.html" title="class Poco::Net::SocketReactor">SocketReactor</a> dispatches the event handlers. </p> <p><a href="Poco.Event.html" title="class Poco::Event">Event</a> handlers (any class can be an event handler - there is no base class for event handlers) can be registered with the <a href="Poco.Net.SocketReactor.html#15420" title="Poco::Net::SocketReactor::addEventHandler()">addEventHandler</a>() method and deregistered with the <a href="Poco.Net.SocketReactor.html#15423" title="Poco::Net::SocketReactor::removeEventHandler()">removeEventHandler</a>() method. </p> <p>An event handler is always registered for a certain socket, which is given in the call to <a href="Poco.Net.SocketReactor.html#15420" title="Poco::Net::SocketReactor::addEventHandler()">addEventHandler</a>(). <a href="Poco.Any.html" title="class Poco::Any">Any</a> 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 <a href="Poco.Net.SocketNotification.html" title="class Poco::Net::SocketNotification">SocketNotification</a> (or a subclass of it) as argument. </p> <p>Once started, the <a href="Poco.Net.SocketReactor.html" title="class Poco::Net::SocketReactor">SocketReactor</a> waits for events on the registered sockets, using <a href="Poco.Net.Socket.html#14992" title="Poco::Net::Socket::select()">Socket::select</a>(). If an event is detected, the corresponding event handler is invoked. There are five event types (and corresponding notification classes) defined: <a href="Poco.Net.ReadableNotification.html" title="class Poco::Net::ReadableNotification">ReadableNotification</a>, <a href="Poco.Net.WritableNotification.html" title="class Poco::Net::WritableNotification">WritableNotification</a>, <a href="Poco.Net.ErrorNotification.html" title="class Poco::Net::ErrorNotification">ErrorNotification</a>, <a href="Poco.Net.TimeoutNotification.html" title="class Poco::Net::TimeoutNotification">TimeoutNotification</a>, <a href="Poco.Net.IdleNotification.html" title="class Poco::Net::IdleNotification">IdleNotification</a> and <a href="Poco.Net.ShutdownNotification.html" title="class Poco::Net::ShutdownNotification">ShutdownNotification</a>. </p> <p>The <a href="Poco.Net.ReadableNotification.html" title="class Poco::Net::ReadableNotification">ReadableNotification</a> will be dispatched if a socket becomes readable. The <a href="Poco.Net.WritableNotification.html" title="class Poco::Net::WritableNotification">WritableNotification</a> will be dispatched if a socket becomes writable. The <a href="Poco.Net.ErrorNotification.html" title="class Poco::Net::ErrorNotification">ErrorNotification</a> will be dispatched if there is an error condition on a socket. </p> <p>If the timeout expires and no event has occured, a <a href="Poco.Net.TimeoutNotification.html" title="class Poco::Net::TimeoutNotification">TimeoutNotification</a> will be dispatched to all event handlers registered for it. This is done in the <a href="Poco.Net.SocketReactor.html#15426" title="Poco::Net::SocketReactor::onTimeout()">onTimeout</a>() method which can be overridden by subclasses to perform custom timeout processing. </p> <p>If there are no sockets for the <a href="Poco.Net.SocketReactor.html" title="class Poco::Net::SocketReactor">SocketReactor</a> to pass to <a href="Poco.Net.Socket.html#14992" title="Poco::Net::Socket::select()">Socket::select</a>(), an <a href="Poco.Net.IdleNotification.html" title="class Poco::Net::IdleNotification">IdleNotification</a> will be dispatched to all event handlers registered for it. This is done in the <a href="Poco.Net.SocketReactor.html#15427" title="Poco::Net::SocketReactor::onIdle()">onIdle</a>() method which can be overridden by subclasses to perform custom idle processing. Since <a href="Poco.Net.SocketReactor.html#15427" title="Poco::Net::SocketReactor::onIdle()">onIdle</a>() will be called repeatedly in a loop, it is recommended to do a short sleep or yield in the event handler. </p> <p>Finally, when the <a href="Poco.Net.SocketReactor.html" title="class Poco::Net::SocketReactor">SocketReactor</a> is about to shut down (as a result of <a href="Poco.Net.SocketReactor.html#15416" title="Poco::Net::SocketReactor::stop()">stop</a>() being called), it dispatches a <a href="Poco.Net.ShutdownNotification.html" title="class Poco::Net::ShutdownNotification">ShutdownNotification</a> to all event handlers. This is done in the <a href="Poco.Net.SocketReactor.html#15428" title="Poco::Net::SocketReactor::onShutdown()">onShutdown</a>() method which can be overridded by subclasses to perform custom shutdown processing. </p> <p>The <a href="Poco.Net.SocketReactor.html" title="class Poco::Net::SocketReactor">SocketReactor</a> is implemented so that it can run in its own thread. It is also possible to run multiple SocketReactors in parallel, as long as they work on different sockets. </p> <p>It is safe to call <a href="Poco.Net.SocketReactor.html#15420" title="Poco::Net::SocketReactor::addEventHandler()">addEventHandler</a>() and <a href="Poco.Net.SocketReactor.html#15423" title="Poco::Net::SocketReactor::removeEventHandler()">removeEventHandler</a>() from another thread while the <a href="Poco.Net.SocketReactor.html" title="class Poco::Net::SocketReactor">SocketReactor</a> is running. Also, it is safe to call <a href="Poco.Net.SocketReactor.html#15420" title="Poco::Net::SocketReactor::addEventHandler()">addEventHandler</a>() and <a href="Poco.Net.SocketReactor.html#15423" title="Poco::Net::SocketReactor::removeEventHandler()">removeEventHandler</a>() from event handlers. </p> </div> <h2>Inheritance</h2> <p><b>Direct Base Classes: </b><a href="Poco.Runnable.html" title="class Poco::Runnable">Poco::Runnable</a></p> <p><b>All Base Classes: </b><a href="Poco.Runnable.html" title="class Poco::Runnable">Poco::Runnable</a></p> <h2>Member Summary</h2> <p><b>Member Functions: </b><a href="Poco.Net.SocketReactor.html#15420" title="Poco::Net::SocketReactor::addEventHandler()">addEventHandler</a>, <a href="Poco.Net.SocketReactor.html#15429" title="Poco::Net::SocketReactor::dispatch()">dispatch</a>, <a href="Poco.Net.SocketReactor.html#15419" title="Poco::Net::SocketReactor::getTimeout()">getTimeout</a>, <a href="Poco.Net.SocketReactor.html#15427" title="Poco::Net::SocketReactor::onIdle()">onIdle</a>, <a href="Poco.Net.SocketReactor.html#15428" title="Poco::Net::SocketReactor::onShutdown()">onShutdown</a>, <a href="Poco.Net.SocketReactor.html#15426" title="Poco::Net::SocketReactor::onTimeout()">onTimeout</a>, <a href="Poco.Net.SocketReactor.html#15423" title="Poco::Net::SocketReactor::removeEventHandler()">removeEventHandler</a>, <a href="Poco.Net.SocketReactor.html#15415" title="Poco::Net::SocketReactor::run()">run</a>, <a href="Poco.Net.SocketReactor.html#15417" title="Poco::Net::SocketReactor::setTimeout()">setTimeout</a>, <a href="Poco.Net.SocketReactor.html#15416" title="Poco::Net::SocketReactor::stop()">stop</a></p> <p><b>Inherited Functions: </b><a href="Poco.Runnable.html#9810" title="Poco::Runnable::run()">run</a></p> <h2>Constructors</h2> <h3><a name="15411">SocketReactor</a></h3> <p class="decl"><a href="Poco.Net.SocketReactor.html" title="class Poco::Net::SocketReactor">SocketReactor</a>();</p> <div class="description"> <p>Creates the <a href="Poco.Net.SocketReactor.html" title="class Poco::Net::SocketReactor">SocketReactor</a>. </p> </div> <h3><a name="15412">SocketReactor</a></h3> <p class="decl">explicit <a href="Poco.Net.SocketReactor.html" title="class Poco::Net::SocketReactor">SocketReactor</a>(<br /> const <a href="Poco.Timespan.html" title="class Poco::Timespan">Poco::Timespan</a> & timeout<br />);</p> <div class="description"> <p>Creates the <a href="Poco.Net.SocketReactor.html" title="class Poco::Net::SocketReactor">SocketReactor</a>, using the given timeout. </p> </div> <h2>Destructor</h2> <h3><a name="15414">~SocketReactor</a> <img src="images/virtual.gif" alt="virtual" title="virtual" style="vertical-align:baseline;" border="0" /> </h3> <p class="decl">virtual ~<a href="Poco.Net.SocketReactor.html" title="class Poco::Net::SocketReactor">SocketReactor</a>();</p> <div class="description"> <p>Destroys the <a href="Poco.Net.SocketReactor.html" title="class Poco::Net::SocketReactor">SocketReactor</a>. </p> </div> <h2>Member Functions</h2> <h3><a name="15420">addEventHandler</a></h3> <p class="decl">void addEventHandler(<br /> const <a href="Poco.Net.Socket.html" title="class Poco::Net::Socket">Socket</a> & socket,<br /> const <a href="Poco.AbstractObserver.html" title="class Poco::AbstractObserver">Poco::AbstractObserver</a> & observer<br />);</p> <div class="description"> <p>Registers an event handler with the <a href="Poco.Net.SocketReactor.html" title="class Poco::Net::SocketReactor">SocketReactor</a>. </p> <p>Usage: </p> <pre>Poco::Observer<MyEventHandler, SocketNotification> obs(*this, &MyEventHandler::handleMyEvent); reactor.addEventHandler(obs); </pre> </div> <h3><a name="15419">getTimeout</a></h3> <p class="decl">const <a href="Poco.Timespan.html" title="class Poco::Timespan">Poco::Timespan</a> & getTimeout() const;</p> <div class="description"> <p>Returns the timeout. </p> </div> <h3><a name="15423">removeEventHandler</a></h3> <p class="decl">void removeEventHandler(<br /> const <a href="Poco.Net.Socket.html" title="class Poco::Net::Socket">Socket</a> & socket,<br /> const <a href="Poco.AbstractObserver.html" title="class Poco::AbstractObserver">Poco::AbstractObserver</a> & observer<br />);</p> <div class="description"> <p>Unregisters an event handler with the <a href="Poco.Net.SocketReactor.html" title="class Poco::Net::SocketReactor">SocketReactor</a>. </p> <p>Usage: </p> <pre>Poco::Observer<MyEventHandler, SocketNotification> obs(*this, &MyEventHandler::handleMyEvent); reactor.removeEventHandler(obs); </pre> </div> <h3><a name="15415">run</a> <img src="images/virtual.gif" alt="virtual" title="virtual" style="vertical-align:baseline;" border="0" /> </h3> <p class="decl">void run();</p> <div class="description"> <p>Runs the <a href="Poco.Net.SocketReactor.html" title="class Poco::Net::SocketReactor">SocketReactor</a>. The reactor will run until <a href="Poco.Net.SocketReactor.html#15416" title="Poco::Net::SocketReactor::stop()">stop</a>() is called (in a separate thread). </p> </div> <div class="description"><p><b>See also:</b> <a href="Poco.Runnable.html#9810" title="Poco::Runnable::run()">Poco::Runnable::run()</a></p></div> <h3><a name="15417">setTimeout</a></h3> <p class="decl">void setTimeout(<br /> const <a href="Poco.Timespan.html" title="class Poco::Timespan">Poco::Timespan</a> & timeout<br />);</p> <div class="description"> <p>Sets the timeout. </p> <p>If no other event occurs for the given timeout interval, a timeout event is sent to all event listeners. </p> <p>The default timeout is 250 milliseconds; </p> <p>The timeout is passed to the <a href="Poco.Net.Socket.html#14992" title="Poco::Net::Socket::select()">Socket::select</a>() method. </p> </div> <h3><a name="15416">stop</a></h3> <p class="decl">void stop();</p> <div class="description"> <p>Stops the <a href="Poco.Net.SocketReactor.html" title="class Poco::Net::SocketReactor">SocketReactor</a>. </p> <p>The reactor will be stopped when the next event (including a timeout event) occurs. </p> </div> <h3><a name="15429">dispatch</a> <img src="images/protected.gif" alt="protected" title="protected" style="vertical-align:baseline;" border="0" /> </h3> <p class="decl">void dispatch(<br /> const <a href="Poco.Net.Socket.html" title="class Poco::Net::Socket">Socket</a> & socket,<br /> <a href="Poco.Net.SocketNotification.html" title="class Poco::Net::SocketNotification">SocketNotification</a> * pNotification<br />);</p> <div class="description"> <p>Dispatches the given notification to all observers registered for the given socket. </p> </div> <h3><a name="15432">dispatch</a> <img src="images/protected.gif" alt="protected" title="protected" style="vertical-align:baseline;" border="0" /> </h3> <p class="decl">void dispatch(<br /> <a href="Poco.Net.SocketNotification.html" title="class Poco::Net::SocketNotification">SocketNotification</a> * pNotification<br />);</p> <div class="description"> <p>Dispatches the given notification to all observers. </p> </div> <h3><a name="15427">onIdle</a> <img src="images/protected.gif" alt="protected" title="protected" style="vertical-align:baseline;" border="0" /> <img src="images/virtual.gif" alt="virtual" title="virtual" style="vertical-align:baseline;" border="0" /> </h3> <p class="decl">virtual void onIdle();</p> <div class="description"> <p>Called if no sockets are available to call select() on. </p> <p>Can be overridden by subclasses. The default implementation dispatches the <a href="Poco.Net.IdleNotification.html" title="class Poco::Net::IdleNotification">IdleNotification</a> and thus should be called by overriding implementations. </p> </div> <h3><a name="15428">onShutdown</a> <img src="images/protected.gif" alt="protected" title="protected" style="vertical-align:baseline;" border="0" /> <img src="images/virtual.gif" alt="virtual" title="virtual" style="vertical-align:baseline;" border="0" /> </h3> <p class="decl">virtual void onShutdown();</p> <div class="description"> <p>Called when the <a href="Poco.Net.SocketReactor.html" title="class Poco::Net::SocketReactor">SocketReactor</a> is about to terminate. </p> <p>Can be overridden by subclasses. The default implementation dispatches the <a href="Poco.Net.ShutdownNotification.html" title="class Poco::Net::ShutdownNotification">ShutdownNotification</a> and thus should be called by overriding implementations. </p> </div> <h3><a name="15426">onTimeout</a> <img src="images/protected.gif" alt="protected" title="protected" style="vertical-align:baseline;" border="0" /> <img src="images/virtual.gif" alt="virtual" title="virtual" style="vertical-align:baseline;" border="0" /> </h3> <p class="decl">virtual void onTimeout();</p> <div class="description"> <p>Called if the timeout expires and no other events are available. </p> <p>Can be overridden by subclasses. The default implementation dispatches the <a href="Poco.Net.TimeoutNotification.html" title="class Poco::Net::TimeoutNotification">TimeoutNotification</a> and thus should be called by overriding implementations. </p> </div> <p class="footer">POCO C++ Libraries 1.3.6-all<br /> Copyright © 2009, <a href="http://pocoproject.org/" target="_blank">Applied Informatics Software Engineering GmbH and Contributors</a></p> </div> </body> </html>
