Add mem_cb functor to use an arbitrary memeber function as an event handler.

[software/eventxx.git] / eventxx

diff --git a/eventxx b/eventxx
index 7bbd6dd4e886fd791ceb3ed509a26b6baad82ae3..94ee1136911125e230063e9eabc3848a0f38fc9b 100644 (file)
--- a/eventxx
+++ b/eventxx
@@ -131,8 +131,8 @@
  * @section Status
  *
  * This library has not been widely used yet, so it lacks proper testing.
- * Because templates are not even compiled when they are not used, don't have to
- * be surprised if you catch a piece of code that doesn't compile. The library
+ * Because templates are not even compiled when they are not used, don't be
+ * surprised if you catch a piece of code that doesn't compile. The library
  * has no support for buffered events yet. It doesn't support the HTTP stuff,
  * and probably never will because that has nothing to do with event handling.
  *
@@ -158,7 +158,7 @@
  *
  * @author Leandro Lucarella <llucax+eventxx@gmail.com>
  *
- * @version 0.1
+ * @version 0.2
  *
  * @par License
  * This program is under the BOLA license (see
@@ -180,6 +180,12 @@
  * callbacks.
  */
 
+/** @example wrapped-functor-way.cpp
+ *
+ * This is a simple example illustrating the usage with an arbitrary member
+ * function as an event handler callbacks.
+ */
+
 /** @example mixed-way.cpp
  *
  * This is a simple example illustrating the usage with a mix of C-like callbacks
@@ -373,6 +379,9 @@ struct time: ::timeval
  * function objects (see eventxx::event, eventxx::timer and eventxx::signal
  * templates). The former are just typedef'ed specialization of the later.
  *
+ * A member function wrapper functor (eventxx::mem_cb) is also included,
+ * so you can use any member function (method) as an event handler.
+ *
  * All events derive from a plain class (not template) eventxx::basic_event, one
  * of the main utilities of it (besides containing common code ;) is to be used
  * in STL containers.
@@ -689,6 +698,38 @@ typedef eventxx::timer< ccallback_type > ctimer;
 /// Shortcut to C-style signal handler.
 typedef eventxx::signal< ccallback_type > csignal;
 
+/**
+ * Helper functor to use an arbitrary member function as an event handler.
+ *
+ * With this wrapper, you can use any object method, which accepts the right
+ * parameters (int, short) and returns void, as an event handler. This way you
+ * don't have to overload the operator() which can be confusing depending on the
+ * context.
+ *
+ * You can see an usage example in the Examples Section.
+ */
+template < typename O, typename M >
+struct mem_cb
+{
+       /**
+        * Member function callback constructor.
+        *
+        * It expects to receive a class as the first parameter (O), and a
+        * member function (of that class O) as the second parameter.
+        *
+        * When this instance is called with fd and ev as function arguments,
+        * object.method(fd, ev) will be called.
+        *
+        * @param object Object to be used.
+        * @param method Method to be called.
+        */
+       mem_cb(O& object, M method) throw():
+               _object(object), _method(method) {}
+       void operator() (int fd, short ev) { (_object.*_method)(fd, ev); }
+       protected:
+               O& _object;
+               M _method;
+}; // struct mem_cb
 
 //@}
 
@@ -781,7 +822,7 @@ struct dispatcher
                                && internal::event_priority_set(&e, priority))
                        throw invalid_priority();
                // XXX HACK libevent don't use const
-               internal::event_add(&e, const_cast< time* >(&to)); 
+               internal::event_add(&e, const_cast< time* >(&to));
        }
 
        /**
@@ -920,10 +961,12 @@ struct dispatcher
         *              processed, if eventxx::NONBLOCK is specified, then this
         *              function returns even if there are no pending events.
         *
-        * @return Not very well specified by @libevent :-/ that's why it
-        *         doesn't throw an exception either.
+        * @return 0 if eventxx::NONBLOCK or eventxx::ONCE is set, 1 if there
+        *         are no more events registered and EINTR if you use the
+        *         @libevent's  @c event_gotsig and return -1 in your
+        *         @c event_sigcb callback.
         */
-       int dispatch(int flags = 0) throw() // TODO  throw(exception)
+       int dispatch(int flags = 0) throw()
        {
                return internal::event_base_loop(_event_base, flags);
        }
@@ -955,8 +998,7 @@ struct dispatcher
 
 }; // struct dispatcher
 
-
-} // namespace event
+} // namespace eventxx
 
 #endif // _EVENTXX_HPP_