Problem: no documentation of the poller concept

Solution: added documentation

src/poller_base.hpp

@@ -40,22 +40,94 @@ namespace zmq
 {
 struct i_poll_events;
 
+// A build of libzmq must provide an implementation of the poller_t concept. By
+// convention, this is done via a typedef.
+//
+// At the time of writing, the following implementations of the poller_t
+// concept exist: zmq::devpoll_t, zmq::epoll_t, zmq::kqueue_t, zmq::poll_t,
+// zmq::pollset_t, zmq::select_t
+//
+// An implementation of the poller_t concept must provide the following public
+// methods:
+//   Returns load of the poller.
+// int get_load() const;
+//
+//   Add a timeout to expire in timeout_ milliseconds. After the
+//   expiration, timer_event on sink_ object will be called with
+//   argument set to id_.
+// void add_timer(int timeout_, zmq::i_poll_events *sink_, int id_);
+//
+//   Cancel the timer created by sink_ object with ID equal to id_.
+// void cancel_timer(zmq::i_poll_events *sink_, int id_);
+//
+//   Adds a fd to the poller. Initially, no events are activated. These must
+//   be activated by the set_* methods using the returned handle_.
+// handle_t add_fd(fd_t fd_, zmq::i_poll_events *events_);
+//
+//   Deactivates any events that may be active for the given handle_, and
+//   removes the fd associated with the given handle_.
+// void rm_fd(handle_t handle_);
+//
+//   The set_* and reset_* methods activate resp. deactivate polling for
+//   input/output readiness on the respective handle_, such that the
+//   in_event/out_event methods on the associated zmq::i_poll_events object
+//   will be called.
+//   Note: while handle_t and fd_t may be the same type, and may even have the
+//   same values for some implementation, this may not be assumed in general.
+//   The methods may only be called with the handle returned by add_fd.
+// void set_pollin(handle_t handle_);
+// void reset_pollin(handle_t handle_);
+// void set_pollout(handle_t handle_);//
+// void reset_pollout(handle_t handle_);
+//
+//   Starts operation of the poller. See below for details.
+// void start();
+//
+//   Request termination of the poller.
+//   TODO: might be removed in the future, as it has no effect.
+// void stop();
+//
+//   Returns the maximum number of fds that can be added to an instance of the
+//   poller at the same time, or -1 if there is no such fixed limit.
+// static int max_fds();
+//
+// Most of the methods may only be called from a zmq::i_poll_events callback
+// function when invoked by the poller (and, therefore, typically from the
+// poller's worker thread), with the following exceptions:
+// - get_load may be called from outside
+// - add_fd and add_timer may be called from outside before start
+// - start may be called from outside once
+//
+// After a poller is started, it waits for the registered events (input/output
+// readiness, timeout) to happen, and calls the respective functions on the
+// zmq::i_poll_events object. It terminates when no further registrations (fds
+// or timers) exist.
+//
+// Before start, add_fd must have been called at least once. Behavior may be
+// undefined otherwise.
+//
+// If the poller is implemented by a single worker thread (the
+// worker_poller_base_t base  class may be used to implement such a poller),
+// no synchronization is required for the data structures modified by
+// add_fd, rm_fd, add_timer, cancel_timer, (re)set_poll(in|out). However,
+// reentrancy must be considered, e.g. when one of the functions modifies
+// a container that is being iterated by the poller.
+
+
+// A class that can be used as a base class for implementations of the poller
+// concept.
+//
+// For documentation of the public methods, see the description of the poller_t
+// concept.
 class poller_base_t
 {
   public:
     poller_base_t ();
     virtual ~poller_base_t ();
 
-    //  Returns load of the poller. Note that this function can be
-    //  invoked from a different thread!
+    // Methods from the poller concept.
     int get_load () const;
-
-    //  Add a timeout to expire in timeout_ milliseconds. After the
-    //  expiration timer_event on sink_ object will be called with
-    //  argument set to id_.
     void add_timer (int timeout_, zmq::i_poll_events *sink_, int id_);
-
-    //  Cancel the timer created by sink_ object with ID equal to id_.
     void cancel_timer (zmq::i_poll_events *sink_, int id_);
 
   protected:
@@ -87,19 +159,26 @@ class poller_base_t
     const poller_base_t &operator= (const poller_base_t &);
 };
 
-//  base class for a poller with a single worker thread.
+//  Base class for a poller with a single worker thread.
 class worker_poller_base_t : public poller_base_t
 {
   public:
     worker_poller_base_t (const thread_ctx_t &ctx_);
-    void stop_worker ();
 
-    // Starts the poller.
+    // Methods from the poller concept.
     void start ();
 
   protected:
+    //  Checks whether the currently executing thread is the worker thread
+    //  via an assertion.
+    //  Should be called by the add_fd, removed_fd, set_*, reset_* functions
+    //  to ensure correct usage.
     void check_thread ();
 
+    //  Stops the worker thread. Should be called from the destructor of the
+    //  leaf class.
+    void stop_worker ();
+
   private:
     //  Main worker thread routine.
     static void worker_routine (void *arg_);