X-Git-Url: http://g0dil.de/git?a=blobdiff_plain;f=Scheduler%2FScheduler.hh;h=a8dc456aed0469edb4052d98339fe717cf86c3d2;hb=553781d9e9bce316dca24ac4f0c42e5613e849e0;hp=a54bed8444ff949e0702d3bfc05eca6aa3bf8c9f;hpb=93db392bf3739914fbf297f4aefa396a2d304d92;p=senf.git
diff --git a/Scheduler/Scheduler.hh b/Scheduler/Scheduler.hh
index a54bed8..a8dc456 100644
--- a/Scheduler/Scheduler.hh
+++ b/Scheduler/Scheduler.hh
@@ -20,11 +20,8 @@
// Free Software Foundation, Inc.,
// 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-// TODO: Fix EventId parameter (probably to int) to allow |-ing without casting ...
-
-
-/** \mainpage The SENF Scheduler library
-
+/** \file
+ \brief Scheduler public header
*/
#ifndef HH_Scheduler_
@@ -47,11 +44,28 @@ namespace senf {
/** \brief Singleton class to manage the event loop
- This class manages a single select() type event loop. A
- customer of this class may register any number of file
- descriptiors with this class and pass callback functions to be
- called on input, output or error. This functions are specified
- using boost::function objects
+ This class manages a single select() type event loop. A customer of this class may register
+ any number of file descriptiors with this class and pass callback functions to be called on
+ input, output or error. This functions are specified using boost::function objects (See Boost.Function)
+
+ The Scheduler is based on a generic handle representation. The only information needed from
+ a handle, is the intrinsic file descriptor. Any object for which the statement
+ \code
+ int fd = retrieve_filehandle(object);
+ \endcode
+ is valid and places the relevent file descriptor into fd can be used as a Handle type. There
+ is an implementation of retrieve_filehandle(int) within the library to handle explicit file
+ descrptors. The Socket library provides an
+ implementation of retrive_filehandle(FileHandle handle). If you want to support
+ some other handle type, just define an apropriate \c retrieve_filehandle function in
+ that types namespace.
+
+ It is important to note, that for every combination of file descriptor and event, only a \e
+ single handler may be installed. Installing more handlers does not make sense. If you need
+ to distribute data to serveral interested parties, you must take care of this yourself.
+
+ \todo Fix EventId parameter (probably to int) to allow |-ing without casting ...
*/
class Scheduler
: boost::noncopyable
@@ -60,16 +74,24 @@ namespace senf {
///////////////////////////////////////////////////////////////////////////
// Types
+ /// \brief Types of file descriptor events */
enum EventId { EV_NONE=0,
EV_READ=1, EV_PRIO=2, EV_WRITE=4, EV_HUP=8, EV_ERR=16,
EV_ALL=31 };
+ /** \brief Template typedef for Callback type
+
+ This is a template typedef (which does not exist in C++) that is, a template class whose
+ sole member is a typedef symbol defining the callback type given the handle type.
+
+ The Callback is any callable object taking a \c Handle and an \c EventId as argument.
+ */
template
struct GenericCallback {
typedef boost::function::param_type,
EventId) > Callback;
};
- typedef boost::function SimpleCallback;
+ /** \brief Callback type for timer events */
typedef boost::function TimerCallback;
///////////////////////////////////////////////////////////////////////////
@@ -82,6 +104,17 @@ namespace senf {
// default destructor
// no conversion constructors
+ /** \brief Return Scheduler instance
+
+ This static member is used to access the singleton instance. This member is save to
+ return a correctly initialized Scheduler instance even if called at global construction
+ time
+
+ \implementation This static member just defines the Scheduler as a static method
+ variable. The C++ standard then provides above guaratee. The instance will be
+ initialized the first time, the code flow passes the variable declaration found in
+ the instance() body.
+ */
static Scheduler & instance();
///@}
@@ -90,23 +123,58 @@ namespace senf {
template
void add(Handle const & handle,
typename GenericCallback::Callback const & cb,
- int eventMask = EV_ALL);
+ int eventMask = EV_ALL); ///< Add file handle event callback
+ /**< add() will add a callback to the Scheduler. The
+ callbeck will be called for the given type of event on
+ the given arbitrary file-descriptor or
+ handle-like object. If there already is a Callback
+ register ed for one of the events requested, the new
+ handler will replace the old one.
+ \param[in] handle file descriptor or handle providing
+ the Handle interface defined above.
+ \param[in] cb callback
+ \param[in] eventMask arbitrary combination via '|'
+ operator of EventId designators. */
template
- void remove(Handle const & handle, int eventMask = EV_ALL);
-
- void timeout(unsigned long timeout, TimerCallback const & cb);
-
- void process();
- void terminate();
+ void remove(Handle const & handle, int eventMask = EV_ALL); ///< Remove event callback
+ /**< remove() will remove any callback registered for any of
+ the given events on the given file descriptor or handle
+ like object.
+ \param[in] handle file descriptor or handle providing
+ the Handle interface defined above.
+ \param[in] eventMask arbitrary combination via '|'
+ operator of EventId designators. */
+
+ void timeout(unsigned long timeout, TimerCallback const & cb); ///< Add timeout event
+ /**< \param[in] timeout timeout in milliseconds
+ \param[in] cb callback to call after \a timeout
+ milliseconds
+ \todo Return some kind of handle/pointer and add
+ support to update or revoke a timeout */
+
+ void process(); ///< Event handler main loop
+ /**< This member must be called at some time to enter the
+ event handler main loop. Only while this function is
+ running any events are handled. The call will return
+ only, if any callback calls terminate(). */
+ void terminate(); ///< Called by callbacks to terminate the main loop
+ /**< This member may be called by any callback to tell the
+ main loop to terminate. The main loop will return to
+ it's caller after the currently running callback
+ returns. */
protected:
private:
+ typedef boost::function SimpleCallback;
+
Scheduler();
void do_add(int fd, SimpleCallback const & cb, int eventMask = EV_ALL);
void do_remove(int fd, int eventMask = EV_ALL);
+ /** \brief Descriptor event specification
+ \internal */
struct EventSpec
{
SimpleCallback cb_read;
@@ -118,6 +186,8 @@ namespace senf {
int epollMask() const;
};
+ /** \brief Timer event specification
+ \internal */
struct TimerSpec
{
TimerSpec() : timeout(), cb() {}
@@ -140,13 +210,20 @@ namespace senf {
bool terminate_;
};
+ /** \brief Default file descriptor accessor
+
+ retrieve_filehandle() provides the Scheduler with support for explicit file descriptors as
+ file handle argument.
+
+ \relates Scheduler
+ */
int retrieve_filehandle(int fd);
}
///////////////////////////////hh.e////////////////////////////////////////
#include "Scheduler.cci"
-#include "Scheduler.ct"
+//#include "Scheduler.ct"
#include "Scheduler.cti"
#endif
@@ -154,4 +231,5 @@ namespace senf {
// Local Variables:
// mode: c++
// c-file-style: "senf"
+// fill-column: 100
// End: