From 7f61bc3d979ef53b867172664694f8fcf9e5bdd0 Mon Sep 17 00:00:00 2001 From: root Date: Fri, 7 Dec 2007 20:13:08 +0000 Subject: document c++ callbacks! --- ev.html | 81 +++++++++++++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 62 insertions(+), 19 deletions(-) (limited to 'ev.html') diff --git a/ev.html b/ev.html index 63ddf3b..efd79da 100644 --- a/ev.html +++ b/ev.html @@ -6,7 +6,7 @@ - + @@ -1738,11 +1738,19 @@ the callback model to a model using method callbacks on objects.

  #include <ev++.h>
-

(it is not installed by default). This automatically includes ev.h -and puts all of its definitions (many of them macros) into the global -namespace. All C++ specific things are put into the ev namespace.

-

It should support all the same embedding options as ev.h, most notably -EV_MULTIPLICITY.

+

This automatically includes ev.h and puts all of its definitions (many +of them macros) into the global namespace. All C++ specific things are +put into the ev namespace. It should support all the same embedding +options as ev.h, most notably EV_MULTIPLICITY.

+

Care has been taken to keep the overhead low. The only data member added +to the C-style watchers is the event loop the watcher is associated with +(or no additional members at all if you disable EV_MULTIPLICITY when +embedding libev).

+

Currently, functions and static and non-static member functions can be +used as callbacks. Other types should be easy to add as long as they only +need one additional pointer for context. If you need support for other +types of functors please contact the author (preferably after implementing +it).

Here is a list of things available in the ev namespace:

ev::READ, ev::WRITE etc.
@@ -1763,17 +1771,50 @@ defines by many implementations.

All of those classes have these methods:

-
ev::TYPE::TYPE (object *, object::method *)
-
ev::TYPE::TYPE (object *, object::method *, struct ev_loop *)
+
ev::TYPE::TYPE ()
+
ev::TYPE::TYPE (struct ev_loop *)
ev::TYPE::~TYPE
-

The constructor takes a pointer to an object and a method pointer to -the event handler callback to call in this class. The constructor calls -ev_init for you, which means you have to call the set method -before starting it. If you do not specify a loop then the constructor -automatically associates the default loop with this watcher.

+

The constructor (optionally) takes an event loop to associate the watcher +with. If it is omitted, it will use EV_DEFAULT.

+

The constructor calls ev_init for you, which means you have to call the +set method before starting it.

+

It will not set a callback, however: You have to call the templated set +method to set a callback before you can start the watcher.

+

(The reason why you have to use a method is a limitation in C++ which does +not allow explicit template arguments for constructors).

The destructor automatically stops the watcher if it is active.

+
w->set<class, &class::method> (object *)
+
+

This method sets the callback method to call. The method has to have a +signature of void (*)(ev_TYPE &, int), it receives the watcher as +first argument and the revents as second. The object must be given as +parameter and is stored in the data member of the watcher.

+

This method synthesizes efficient thunking code to call your method from +the C callback that libev requires. If your compiler can inline your +callback (i.e. it is visible to it at the place of the set call and +your compiler is good :), then the method will be fully inlined into the +thunking function, making it as fast as a direct C callback.

+

Example: simple class declaration and watcher initialisation

+
  struct myclass
+  {
+    void io_cb (ev::io &w, int revents) { }
+  }
+
+  myclass obj;
+  ev::io iow;
+  iow.set <myclass, &myclass::io_cb> (&obj);
+
+
+
+
w->set (void (*function)(watcher &w, int), void *data = 0)
+
+

Also sets a callback, but uses a static method or plain function as +callback. The optional data argument will be stored in the watcher's +data member and is free for you to use.

+

See the method-set above for more details.

+
w->set (struct ev_loop *)

Associates a different struct ev_loop with this watcher. You can only @@ -1782,13 +1823,14 @@ do this when the watcher is inactive (and not pending either).

w->set ([args])

Basically the same as ev_TYPE_set, with the same args. Must be -called at least once. Unlike the C counterpart, an active watcher gets -automatically stopped and restarted.

+called at least once. Unlike the C counterpart, an active watcher gets +automatically stopped and restarted when reconfiguring it with this +method.

w->start ()
-

Starts the watcher. Note that there is no loop argument as the -constructor already takes the loop.

+

Starts the watcher. Note that there is no loop argument, as the +constructor already stores the event loop.

w->stop ()
@@ -1822,9 +1864,10 @@ the constructor.

} myclass::myclass (int fd) - : io (this, &myclass::io_cb), - idle (this, &myclass::idle_cb) { + io .set <myclass, &myclass::io_cb > (this); + idle.set <myclass, &myclass::idle_cb> (this); + io.start (fd, ev::READ); } -- cgit v1.2.3